ai:skills › d3-f-design · version 1 ·
HistoryMarkdown
name
d3-f-design
description
Design — how a project's documents are kept: work per feature and behaviour codes, the doc layers, the Specification on small projects, topic-first building, UI design, blurbs, and its checks. Get skills only from /api/v2/skills/d3.
feature
design
concepts
[feature, code, layer, spec, build, ui, blurb, check]
tags
#skill #feature #d3skill #wip

d3-f-design✎ edit

Intro✎ edit

How a project's Spec, Design and tests are kept, per feature and behaviour code.

A project's design is kept per feature: one short id shared by its spec, design, implementation and test sections, and one code per behaviour it promises, so anyone can follow a promise from the spec to the code that keeps it. This skill says how those documents are kept. What lives elsewhere: tickets and design calls d3-f-pipeline › ticket_write, d3-f-pipeline › item_ask; design tests d3-f-tests › test_write; drafts and publishing d3-f-drafts; the record of decisions d3-f-history › historyEntry_recordDecision; look rules d3-f-styles › control_use; mockups d3-f-cdn › design_mockup; Help and the Toolbox d3-f-help › help_write.

Essentials✎ edit

  • R-design-1 MUST work per feature: its sections in every layer share one {#id} and change together, in the same change.
  • R-design-2 Every behaviour is one spec line ending with a code (^waitlist-1); NEVER renumber a code or reuse a retired one.
  • R-design-3 Spec says what, Design says how; a spec line says what is — NEVER who decided it or when.
  • R-design-4 MUST write a test line for every spec line in the same change, before any ticket for it.
  • R-design-5 Before filing work for a builder, ask: can this be a topic? Code only for a route that doesn't exist or must change, a built-in block, or core behaviour.
  • R-design-6 Change a feature, update its feature skill in the same change.
  • R-design-7 MUST say where to look: link every page, topic, draft and section you touched, and for features end with one system-view link.
  • R-design-8 Design stays implementation-neutral: a kind of mechanism, never a product or language.
  • R-design-9 NEVER design a second hand-kept list of something the code declares (routes, codes, settings, messages); NEVER design words or numbers a person may change into code.
  • R-design-10 MUST keep the project's class model current: a change that adds, renames or reshapes a thing the project keeps (an object with its own fields, states or links) updates its class in the project's Spec: topics in the same change.

Concepts✎ edit

feature✎ edit

A spec section with a short id on its heading: ## Waiting lists {#waitlist}. Also called: a capability, "the waiting-list thing". Fields: its {#id}; one sentence of what it is; its behaviour lines; the same {#id} on its Design, implementation and test sections.

feature_write✎ edit

  • Summary: one {#id} across the layers, changed together in one change.
  • When: adding or changing what a project does.
  • Needs: the person's ask; the feature's existing sections, if any.
  • Call: drafts of the layers (d3-f-drafts › draft_save, one section at a time: d3-f-topics › section_write).
  • Rules: R-design-1, R-design-4, R-design-6, R-design-10. The class model is a layer like the others: declare or change the class (d3-f-domain › class_declare), check it (d3-f-domain › domain_check), and name it in the feature's Spec section. A list the feature keeps (its states, kinds, roles) is an $enum there, not prose. Every new user-facing feature gets its Toolbox tile and Help section in the same change (d3-f-help › toolbox_addTile). Record only design and implementation decisions in the docs and the history; small style changes live only in the commit. A rule changed because of an issue says the issue: a Why: with what happened, so nobody undoes it without seeing the failure.
  • Errors: E_DRAFT_CHANGED (409) → re-read, merge, save again (d3-f-drafts › draft_merge).
  • Gotchas: until the new skills are the default, a rule added to a live d2-* skill also goes into its feature skill in the same change.

feature_report✎ edit

  • Summary: finishing feature work, end with the system-view link showing exactly what you touched.
  • When: you report finished work on features to a person.
  • Needs: the codes and section ids you touched.
  • Call: https://<project host>/system?show=<codes or ids>[&cols=spec,design,impl,tests] Also: data: GET /api/v2/system.
  • Rules: R-design-7. The system view is one row per feature id across the layers, and whether it is built and tested; the person walks your changes with Next change.
  • Errors: —
  • Gotchas: —

code✎ edit

A behaviour's id: the feature's short name and a number, at the end of its spec line — - A full event puts new sign-ups on the waiting list. ^waitlist-1. Also called: behaviour code, requirement id; shown as a WAITLIST-1 chip.

code_write✎ edit

  • Summary: write ^<feature>- and let d2 number it; one line, one behaviour, one code.
  • When: every behaviour line you add.
  • Needs: the feature's short name.
  • Call: in the spec draft: - <what is true>. ^<feature>-.
  • Rules: R-design-2, R-design-3. Codes are unique: none given twice; a dropped one is struck through, never reused. No names, dates or item numbers in the line — they go in the history entry and the item; a how: [[Design#…]] pointer is fine.
  • Errors: a chip that doesn't resolve → the line was renumbered or removed: restore it, or point at the new one.
  • Gotchas: in a domain Spec: topic a $ line meant only as an example must sit in backticks or a code fence, or the topic won't compile (d3-f-domain › domain_check).
  • Summary: the other layers point back with [[Spec#^<code>]]; tests start with the code; code carries // covers:.
  • When: a design, implementation or test line deals with that behaviour.
  • Needs: the code.
  • Call: end the line with [[Spec#^waitlist-1]] (two links if it covers two) Also: a test's name starts WAITLIST-1 … · source carries // covers: waitlist-1.
  • Rules: A ticket names what it changes: its ## Changes lists every code it adds or changes with the line as it will read, and supersedes the existing ones it changes (d3-f-pipeline › ticket_write).
  • Errors: E_TICKET / E_TICKET_WARN → a ticket part, field or supersedes code is missing (d3-f-pipeline › ticket_check).
  • Gotchas: —

layer✎ edit

One level of a project's documents. Also called: the docs, the doc layers. The layers: Spec — what (one sentence per feature, then its behaviour lines). SpecUi — screens, behaviour and flow, with one Look and feel section (the common look rules and the shared UI pieces). Design — how, implementation-neutral: mechanisms, routes, fields, codes; each feature section ends with Routes and codes. DesignRoutes — every route, built or Planned. SpecTest — the design tests. An implementation's own topics — As built (no code references, no versions), Code, Routes, Test (their names are the project's facts). Small and big: a small project keeps it all in its spec topic (spec, then design and tests under their own headings); a bigger one splits the layers into topics.

layer_place✎ edit

  • Summary: what goes in Spec, how goes in Design; routes, fields, mechanisms and numbers never sit in a spec line.
  • When: writing or moving any line.
  • Needs: —
  • Call: — (which draft the line goes in).
  • Rules: R-design-3, R-design-8. Design is the design as it will be, not how today's build does it; closing the gap is done through tickets. UI decisions live in the docs, not only in items or code: every UI change carries its SpecUi line and a layout test, so another build in another stack looks the same. Errors you design are one self-fixing line plus a pointer to a skill section (for AIs) or a Help section (for people): d3-f-errors › error_write.
  • Errors: —
  • Gotchas: —

layer_routes✎ edit

  • Summary: a feature's planned routes, settings and error codes go in its Design Routes and codes and in DesignRoutes' Planned block; built ones come from the code.
  • When: a design adds or changes any of them.
  • Needs: what is built today: GET /api/v2/routes?feature=<id> (one line a route, under 4K).
  • Call: the Design and DesignRoutes drafts.
  • Rules: A route line names a feature that exists. Only what is planned: a release drops its built rows from DesignRoutes (Design › declared); never copy built routes into a topic.
  • Errors: —
  • Gotchas: —

layer_asBuilt✎ edit

  • Summary: builders write only their implementation's own topics and send suggested updates for the design layers.
  • When: closing built work.
  • Needs: what was built and where it differs.
  • Call: the implementation's As built draft Also: an As built note on the item (d3-f-pipeline › item_finish) with suggested updates, one per line, naming the doc and section.
  • Rules: The design layers are changed only by the design's author, who folds the suggestions in. As built differing from the design needs an Accepted line or a design change.
  • Errors: —
  • Gotchas: —

layer_moved✎ edit

  • Summary: a moved or superseded section keeps a MOVED note; nothing still cites it.
  • When: text moves between topics.
  • Needs: where it went.
  • Call: d3-f-topics › topic_moved.
  • Rules: —
  • Errors: —
  • Gotchas: —

spec✎ edit

The project's own specification topic. Also called: the Specification (hero, creator), the spec, AiSpec:PROJECT on older projects. On hero and creator it is what the person asked for, in their words: a ## heading per app or thing with its {#id} and one line of what they asked; a line per feature under it with its {#id} (Title: what it does). It opens with Your AI keeps this page as it builds things for you, from your chat. You can edit it too. On pro the same topic is the project's specification, so nothing is lost when the project moves up. Beside it: the history (decisions and changes, d3-f-history); ToDo:PROJECT on pro and master (creator keeps what's left as parked pipeline items, hero has neither) — frontmatter name, description, project, tags: ai, todo; one - [ ] **Short title.** What needs doing. line each, done ones ticked as - [x] YYYY-MM-DD · … under ## Done.

spec_small✎ edit

  • Summary: keep the Specification as you build: feature: <id> marks a row built, a Story: checked.
  • When: hero and creator projects — every time you build or change something for the person.
  • Needs: the feature's id in the Specification.
  • Call: the Spec topic (d3-f-topics › topic_write) Also: feature: <id> (or features: a, b) in the frontmatter of each page, app, rules topic or other part.
  • Rules: A part or story naming an id the Specification lacks shows under Not described yet: add the line. The story: d3-f-tests › story_check.
  • Errors: —
  • Gotchas: a PUT replaces the whole topic: read it, change it, write it back.

spec_follow✎ edit

  • Summary: read the spec and recent decisions first; follow them; update the spec when something is agreed.
  • When: resuming work on a project; when something is agreed, deferred or done.
  • Needs: —
  • Call: GET the spec topic · d3-f-history › historyEntry_read (type=decision) · the ToDo: topic.
  • Rules: Don't reopen recorded decisions. A request that contradicts the spec: say so, and change the spec once they confirm. Add what's deferred or promised to the to-do list, tick what's done, offer the next one when asked what's next. A bigger feature may have its own spec (AiSpec:<name>; frontmatter name, description, tags: ai, spec, status: draft, agreed, building, done), linked from the project's.
  • Errors: —
  • Gotchas: —

spec_format✎ edit

  • Summary: free-form or OpenSpec — ask the person once, keep the answer, convert only when asked.
  • When: the first time a project needs a spec.
  • Needs: —
  • Call: ask; keep the answer as a line in Memory:preferences Also: OpenSpec's shape and changes: d3-f-topics › openspec_changes.
  • Rules: If the preference is already recorded, don't ask.
  • Errors: an OpenSpec PUT answering openspec: {ok: false, errors} → fix the errors before saying it's done; warnings too, unless the person says not to.
  • Gotchas: —

build✎ edit

How a change gets made: as a topic, or as code. d2 is built with d2 — pages, home and Help text, skills, templates, embedded widgets, App: pages and the look of built-in blocks are topics.

build_asTopic✎ edit

  • Summary: before filing work for a builder, ask whether a topic can do it.
  • When: every change, before any ticket.
  • Needs: what must change, and where it lives today.
  • Call: the topic's draft (d3-f-pages › embed_write, d3-f-styles › style_editBase, d3-f-help › help_write).
  • Rules: R-design-5. Prefer embeds in simple topics over App: topics where either works; a hard-coded page moves to a topic the next time it changes. <style> in a topic is stripped: rules every page needs go in the base style, scoped to what they style, written from the block's real markup in every state, as a person sees it.
  • Errors: —
  • Gotchas: Why: one set of on-page steps was ticketed twice as code; the whole fix was CSS in the base style plus a live test.

build_declared✎ edit

  • Summary: structure is declared once in code and listed from it; words and numbers a person may change are topics; how-to is Help.
  • When: a design adds a route, an error code, a notice, a label, a limit, a role or a status, or any text on a built-in view.
  • Needs: which of the four kinds each new thing is (Design › declared).
  • Call: place each one: a route or a code → the ticket says to declare it on its route row with its feature, and the feature skill's action and Errors line change in the same change (R-design-6) · a notice's or plain page's words → a line in Settings:Messages · a label, colour or order of a role or status → Settings:Process · a limit, a price or a plan's name → Settings:Quotas · how to use a view → its Help page, never a note on the view.
  • Rules: R-design-9, R-design-5. A new feature gets one id used by its Spec section, its feature skill's feature: and its routes. A settings line always has a built-in default; a design never depends on the topic being there. Until the settings topics are built (Design › declared says what is), the ticket names the constant to change and the topic line it will become.
  • Errors: —
  • Gotchas: Why: the API page, the error catalogue and the route topics were three hand-kept lists of one thing; the catalogue grew to 214K in a draft nobody kept.

ui✎ edit

What a person sees. Also called: the screen, the page, the look.

ui_mockup✎ edit

  • Summary: show, don't describe — a visual mockup for any screen or UI change, and it is the ticket's first link.
  • When: a person asks for, or a design changes, anything they will look at.
  • Needs: SpecUi's Look and feel section, read first.
  • Call: while you review it with your person, a mockup that copies a real page is an App topic App:Mockup-<feature>-<name>-v<n> (opened at /app/<name>, shown with ESP); the one they choose goes into the Focus it belongs to, as a topic member. When that Focus is sent or the work is done: move it to the CDN (d3-f-cdn › design_mockup, designer/mockups/<feature>/<name>.txt), link it from SpecUi and the ticket, and delete the App topic; alternatives they didn't choose are deleted. A mockup that isn't a page copy goes straight to the CDN.
  • Rules: One style per kind of control (action buttons, dropdowns, tabs) on every page (d3-f-styles › control_use); a new shared piece is added to Look and feel (d3-f-styles › control_addKind). A ticket describes the page and names earlier mockups and the shared kinds — no mockups made only for builders.
  • Tag every mock mock (razie, 2026-10-10: "all mocks must be tagged mock"). This covers a mockup topic (App:/Page: Mockup-*, a page copy, a try copy, a reference copy) in its frontmatter tags:, a topic whose job is mocks (as Blurb), and every mock file on the CDN (upload with ?tags=mock,<feature>). Then GET /api/v2/topics?tag=mock and GET /api/v2/cdn?tag=mock find them all. A build script that writes a mockup keeps the tag in its sources.
  • Errors: —
  • Gotchas: —

ui_artifact✎ edit

  • Summary: a finished designed piece goes in as it is: wire only what's marked.
  • When: building from a designed artifact (d3-f-cdn › design_accept).
  • Needs: the artifact's link from the ticket.
  • Call: — (drop it in; wire data-wire bindings and links).
  • Rules: Restyling or reshaping it is a design call (d3-f-pipeline › item_ask), not the builder's to make.
  • Errors: —
  • Gotchas: —

blurb✎ edit

A feature's marketing text and the pieces made for it (animations, pictures), in the project's Blurb topic, made the first time the project does blurbs: the ongoing place your person finds blurbs and things to put in various places. Also called: the pitch, marketing copy.

blurb_write✎ edit

  • Summary: for an approved or shipped feature: headline, one-liner, paragraph, proof points from built spec lines.
  • When: a design is approved, or the feature ships.
  • Needs: the feature's spec lines and whether each is built.
  • Call: add the entry at the top of Blurb (newest first): the headline and text on the page, then the animation on its own (a dark embedhtml widget, like the landing's pipeline, no text inside it), then what backs it. With ESP on, take your person to the new entry (→ esp_go).
  • Rules: Every blurb is dark. Every proof point cites a spec line that exists and is built (or says coming). With its designed artifacts: file links, embedded pictures, an image snapshot next to each HTML piece — diagrams dark on a dark card, never on white.
  • Errors: —
  • Gotchas: —

check✎ edit

A watch's check on this feature (d3-f-guard-reports › watch).

check_design✎ edit

  • Summary: the spec watch: ten checks that the layers agree, resolve and are tested.
  • When: daily and after each checkpoint, after d3-f-pipeline › check_doneItems.
  • Needs: topics tagged d2-spec, d2-design, DesignRoutes, MarketingBlurbs, their histories.
  • Call: published reads (d3-f-guard-reports › report_read):
    1. Aligned: every {#id} in Spec and SpecUi has a Design section with the same id, and the reverse.
    2. Routes and codes: every Design feature section ends with it; every route, page and code named is in DesignRoutes (built or Planned); every route line names a feature that exists.
    3. Resolves: links, anchors, behaviour codes cited in Design, SpecUi and tests, and item ids all exist.
    4. Unique codes: no code given twice, none reused after retirement.
    5. What, not how: a spec line carrying the how.
    6. Principles: a design against a standing principle at the top of Spec — quote both.
    7. Decided, then carried: a Decided or Accepted line not yet in the section's text; As built differing from the design with no Accepted line.
    8. Superseded still cited: text marked superseded or moved that others still point to.
    9. Blurbs: proof points cite real, built lines; every artifact link resolves.
    10. Tested: every Spec or SpecUi line added or changed since the last run has a code and a test line.
  • Rules: Owner: the designers' lane; gaps only a builder can fill marked so, same batch.
  • Errors: —
  • Gotchas: —

check_skills✎ edit

  • Summary: the watcher: every way-of-working rule has its counterpart in the skills, and the skills stay small.
  • When: every watcher run.
  • Needs: the ways-of-working doc people read; the skills; your last report's sizes.
  • Call: published reads · GET /api/v2/skills/sizes (per role: always, lookup, total characters).
  • Rules: Each rule in the ways-of-working doc has its counterpart in the skills, and the reverse; a finding is fixed in the skill, never by loosening the people's doc. Sizes are a standing line per role with the change since your last report; always up more than 10% in 7 days, or over about 20,000 characters → a finding for the designers' lane (trim, or move behind a pull). Nothing is refused over size.
  • Errors: —
  • Gotchas: —

check_skillsCurrent✎ edit

  • Summary: the spec watch: each feature skill against the current Spec, Design and As built.
  • When: daily and after each checkpoint, after check_design.
  • Needs: the published feature skills; Spec, Design, DesignRoutes, the error catalogue, the implementation's As built and Routes, and their histories.
  • Call: published reads (d3-f-guard-reports › report_read), per feature skill:
    1. Feature: its feature: id resolves to a Spec section.
    2. Routes: every route in a Call exists in DesignRoutes or the implementation's Routes with the same method, and isn't marked removed.
    3. Codes: every E_ / N_ code in the skill exists in the catalogue (d3-f-errors › catalogue_check); every code the feature's Design names is in the skill's Errors.
    4. Fields and states: each one listed under a concept is in the feature's Design.
    5. Stale: the feature's Spec, Design or As built section changed (topic history) after the skill's last version — quote the changed line and the skill line it touches.
    6. Uncovered: a behaviour code of the feature that an agent acts on and no action's Rules mention.
    7. Links: a cross-link or see #… that doesn't resolve.
  • Rules: One finding per skill, its lines listed. Owner: the designers' lane. The summary line adds skills current: a of b; stale c.
  • Errors: —
  • Gotchas: —

check_skillsMatch✎ edit

  • Summary: the watcher: roles and features fit — Uses resolve, no orphans, every start under budget.
  • When: every watcher run.
  • Needs: the published role and feature skills; the project's permissions and level; each role's compiled start.
  • Call: published reads, plus each role's start from the skills API:
    1. Resolves: every Uses and extras entry of every role skill names a real action.
    2. No repeats: a project role doesn't repeat a base Uses line; a project feature doesn't share a base feature's name.
    3. Orphans and strangers: actions no role uses; a role name inside a feature skill.
    4. Taught but not allowed: a role taught an action its permissions never allow, or a feature above its level.
    5. Duplicates: the same rule or route in two feature skills.
    6. Workflows: every step names an action in that role's Uses.
    7. Budget: each role's compiled start is under the budget.
  • Rules: A standing line per role (start size, Uses count); findings for the rest. Owner: the designers' lane.
  • Errors: —
  • Gotchas: —

Errors✎ edit

  • E_TICKET / E_TICKET_WARN — a ticket part, field or supersedes code is missing or looks wrong. see #code_link
  • a Spec: topic that won't compile — a $ example line outside backticks. see #code_write
  • openspec: {ok: false, errors} — fix before saying it's done. see #spec_format
  • a code chip that doesn't resolve — the line was renumbered or removed. see #code_write
  • E_DRAFT_CHANGED (409) — the draft moved under you → re-read, merge, save. see #feature_write