10 Commits

Include renames

Author	SHA1	Message	Date
bvandeusenandClaude Opus 5	8087ba4db0	feat(design): a project reports drift in its own recorded components ... The check has taken a project id since it was written — check_snippets_against_ system(user_id, design_system_id, project_id=0), and the route has always read ?project_id=. Nothing on the frontend ever passed one and no project-side surface existed, so the capability shipped and stayed unreachable. A Design tab on the project, beside Systems and Rules, reporting three things per snippet: no such token var(--x) the system doesn't declare. Renders as NOTHING — no error, no failing test, just an element quietly unstyled. Leads for that reason. defines its own a component minting a custom property instead of reaching for the shared one. This is the DRY finding and the reason the surface exists: the codebase re-solving a solved problem, one component at a time, visible only when someone changes the shared value and half the components don't move. write the token a literal the sheet says to stop writing, paired with what to write instead. Three empty states, kept distinct, because collapsing them is how a check comes to sit dead: no design system bound, no snippets recorded (nothing was checked), and checked-and-clean. The last one says how many were checked. Bound to the SAVED pointer rather than the sidebar picker's draft, so an unsaved change can't make the tab report against a system the project isn't using. Scope is recorded code, per the operator: snippets are what Scribe holds, and a repository's own sources are checked where they live, by that project's CI. Step 3 of milestone #274. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs	2026-08-04 10:41:49 -04:00
bvandeusenandClaude Opus 5	174ec8af46	feat(design): the starter-role checklist, in the creation UI ... Rule #27 — the backend half shipped without a surface an operator can touch, so this is the other half of #2349. StarterRolePicker is a component rather than inline markup because DesignSystemsView has TWO creation forms: the empty state is a sibling branch of the body, not a parent, so a form written into one is unreachable from the other. Inlining the checklist would have made it the next thing in this codebase defined twice and free to drift — which is what the button migration spent nine commits undoing. What it offers is names and purposes, never values. "Named now, valued later": a role you haven't filled shows as to-be-decided, while a role that doesn't exist is what gets written as a literal instead. Every group unchecks individually, and the prefix is editable because `--fs-` is one family's convention, not the product's. Three deliberate details: - All groups checked by DEFAULT, and that default lives in the UI, not the service. create_design_system treats None and [] alike (seed nothing) so it can never write 40 rows into a system whose caller never asked; a UI default is visible and reversible before the click. Different layers, different safe answers. - A failed catalogue fetch is NOT fatal and does not read as an error. Starter roles are an accelerator, not a prerequisite — the form still creates, and the operator adds tokens by hand. - The refs are not cleared after a successful create. The picker owns them and re-seeds on mount; resetting here would race that and silently create the next system with no roles. props + defineEmits rather than defineModel, matching TagInput and the rest of components/. defineModel is available (Vue 3.5) and would be shorter, but being the only file in the codebase using a different binding idiom costs more than the lines it saves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs	2026-08-03 11:45:48 -04:00
bvandeusen	1fde646c60	feat(design-systems): formulas — derived tokens that follow their source ... Operator: "build in a way to support formulas like this so that the colors shift as expected and have less to clean up when testing color changes." The storage needed no change at all, which is the good news. A formula is just a value: --fs-accent-soft: color-mix(in srgb, var(--fs-accent) 15%, transparent) It passes the value sanitiser untouched (verified, and now pinned by a test — had `color-mix(... var(...) ...)` been rejected as unsafe, derivation would have needed a storage shape of its own), and the browser resolves the `var()` at use time. Change `--fs-accent` and everything derived from it shifts. **One declaration covers every mode**, and that is the "less to clean up" part. A derived token written once in the base layer follows its source through dark mode automatically, because `var()` resolves where it is USED rather than where it is written. A stored computed literal would need a row per mode and would silently stop tracking the source the moment the source changed — the whole problem this avoids. What derivation DID need is the check. A formula pointing at a token that does not exist is invalid-at-computed-value-time: the browser drops the declaration outright and the token has no value. No error, no warning, nothing in the toolchain notices — the same family as `--color-accent`, `_parent_map`, and the scripted edit whose anchor matched nothing. So `derivation_report` returns three things alongside the sheet: which tokens are computed and from what, which formulas point at nothing, and which derive from each other in a loop. CSS resolves a loop to nothing rather than hanging, so the cycle check is about telling the operator, not protecting the renderer — but a token that quietly resolves to nothing is exactly what is worth being told. A self-reference with a fallback (`var(--fs-x, 8px)`) is deliberately not a dependency; counting it would report every such token as a one-node loop. The UI leads with broken formulas, then loops, then the healthy derived set — the first two are unambiguously wrong, where a duplicate value is a judgement call.	2026-07-31 09:51:54 -04:00
bvandeusen	23a385e2db	revert(design-systems): drop the rulebook import — a migration, not a feature ... Operator's call, and it corrects a scope error rather than a bug: "this is a path for a user to go from a rulebook to a design system. we don't need to build this path in the app itself ... you should be the one that does the import ... going forward no one else should have to do such a migration." Right. Nobody starting from a design system will ever go rulebook -> system, so the whole path was permanent product code serving a single act on one install. Rule #22: remove it, don't flag it off. Gone from the service, the REST route, the MCP tool, the UI panel, the API client and its tests. There is a second consequence I had missed, and it is the better argument. The parser was WORSE at this than doing it by hand. `propose_tokens` leaves radius steps and type sizes valueless because "Small 4px" is not a hex and nothing here parses it — a limitation I documented carefully and shipped anyway. But that limitation only exists because the importer had to run unattended. Done as work rather than as a feature, those values are just read and written, and the result is a complete design system instead of one with a dozen blanks and a count explaining them. Scaffolding built around my own absence from the loop, when I am the loop. KEPT: `extract_expectations` and `design_expectations` in services/design_rulebook_import.py. The live drift panel still reads them until it is repointed at a resolved design system (#2295), and removing them now would take the /design page's only content with it. They go with that change, not this one.	2026-07-31 09:46:12 -04:00
bvandeusen	0f80b790c7	feat(design-systems): central prose — guidance on the system, rationale on tokens ... Last piece of the architecture in #2296. The operator: "the prose doesn't have to live as one offs, there's a central system for managing it." Two fields, both free-form: design_systems.guidance the narrative a token table cannot hold — aesthetic, voice and tone, what is deliberately out of scope. design_tokens.rationale WHY a token is this value, which is a different question from `purpose` (what it is FOR). "Success equals Moss, aligned by design" is a rationale; "page bg, deepest surface" is a purpose. Rules carry the first routinely and a token row had nowhere to put it. Free-form rather than a column per category, deliberately. A schema with `voice`, `aesthetic` and `scope` columns would bake one rulebook's table of contents into every install (rule #115), leaving the next install three empty columns and nowhere for what it actually cares about. Both nullable: a design system with no prose at all is complete, not a draft. `rationale` cascades like `purpose` — deepest non-empty wins — so an app overriding a colour keeps the family's reasoning rather than blanking it. Same argument as `supersedes`: the override was about the value, not the meaning. In the generated sheet the inline comment prefers `purpose` and falls back to `rationale`, so a token carrying only the why still says something instead of rendering bare.	2026-07-30 21:52:16 -04:00
bvandeusen	46d88f9e7e	feat(design-systems): check the components against the sheet they claim to use ... "The snippets use the tags from the sheet" was a relation nobody could verify. Now it is three checks, and all three currently fail SILENTLY in this codebase: unknown `var(--x)` where the system declares no `--x`. Renders as nothing at all — no error, no failing test, no visual clue beyond the element quietly not being styled. superseded literals a value the sheet said to stop writing, paired with the token to write instead. Only possible because `supersedes` is declared rather than inferred. local definitions custom properties a snippet mints for itself instead of reusing the sheet's — the bloat a shared sheet exists to prevent, where a value stops being reused and starts being restated per component. The first is not hypothetical. Writing DesignSystemsView.vue earlier in this same session I used `--color-accent` throughout; it does not exist, and nothing in the toolchain noticed. This check is the thing that would have. A token that is both defined and read locally is reported ONCE, as an unknown reference — "--btn-bg does not exist in the sheet" is the more precise statement of the same problem, and reporting both would double-count one fact. Literal matching is boundary-aware and case-insensitive: `#fff` must not fire inside `#ffffff` (different colours, and a finding on the wrong one sends someone to change correct code), while `#FFFFFF` in a rulebook has to match `#ffffff` in a stylesheet — the same trap `normalize_hex` exists for. Snippets with nothing to report are omitted entirely. A list of everything that is fine is a list nobody reads twice — the same principle the auto-inject menu and the drift panel are both built on. Two integration mistakes fixed while wiring it: `list_snippets` returns `(rows, total)` and caps its limit at 100, and `get_snippet` returns a Note model rather than a dict. The list rows carry a preview, not the code, so the check reads each full body — checking the preview would have reported on a truncation.	2026-07-30 21:47:47 -04:00
bvandeusen	b0a7d9e89b	feat(design-systems): the master sheet — purpose tokens, not per-element values ... Operator's new requirement (#2299, architecture in #2296): a design system does not just hold tokens, it generates and manages a master CSS sheet. That settles the milestone's open "authority mechanism" question — the record is authoritative because the stylesheet comes out of it. **The sheet is shaped by purpose and styles no elements.** It declares custom properties, grouped by what they mean, and contains no `.btn-primary`, no `table`, no `input`. That is the design, not a shortcut: a sheet that styled elements would restate the same handful of values once per element and grow with the UI, where purpose-named values are stated once and reused. Components live as SNIPPETS that reference these names — a surface that already exists and already carries prose, locations, drift checks, merge and write-path recall. A token named after an element (`--fs-button-bg`) is the smell that the two have been mixed; a purpose name (`--fs-action-primary`) is reused across all of them. Alongside the CSS the endpoint returns what the text cannot say for itself: which tokens are still valueless, and which VALUES are declared under more than one name. The second is the operator's "reuse consistent values" constraint made checkable — and it reports rather than refuses, because a design system legitimately aligns colours on purpose ("Success = Moss, by design") and only a human knows which case it is. Mode maps to selector the way the codebase already does it: base on the root selector, every other mode layered on `[data-theme="…"]`. The root selector is a PARAMETER — #251 recorded that a container-scoped preview cannot use `:root`, so hardcoding it would have made the generator useless to the preview surface. A token the rulebook names but states no value for is emitted as a commented-out declaration IN ITS GROUP rather than dropped. Its absence is the finding, and a comment puts that finding where the reader already is. Values are validated, not escaped, and this is a real boundary rather than tidiness: design systems are shareable records (rule #47), so `red; } body { display: none` in a system shared with you would otherwise inject CSS into your page. A value containing `{ } ; @ < >`, a comment delimiter or a newline is REFUSED and rendered as a comment saying so — rejecting beats stripping, since a partially-sanitised value is one the operator never wrote and the sheet's whole claim is that it is the record. Not in scope, and deliberately: serving this as the app's actual stylesheet. Generating and exposing a sheet is reversible; swapping theme.css for a generated one is not, and it should be an explicit call rather than a side effect.	2026-07-30 21:42:08 -04:00
bvandeusen	4dc57f8ab2	feat(design-systems): import a design system out of a rulebook's prose ... Milestone #254 step 3 (#2288). Reuses #251's prose extractor as the reader and adds the part that makes it an import rather than a list of claims. **The join is the whole trick.** A rulebook states a design system in two places and neither half is a token: one rule names the colours ("Obsidian #14171A (page bg, deepest surface)"), another names the custom properties (`--fs-obsidian/iron/slate`). The import pairs them on the word — `--fs-obsidian` ends with `obsidian` — which is the only reason it produces something usable instead of seventy empty names. The parenthetical becomes the token's purpose, which is the field a bare hex could never carry. **Prohibitions arrive as replacements, per the operator's reframe.** Rule 52 declares Parchment and forbids pure white in one breath, so the import emits "write --fs-parchment instead of #ffffff" — the same fact stated forwards. It attaches to the FIRST token that rule supplied a value for, not to every token of that rule, because claiming Vellum is also the replacement for white would be putting words in the rulebook's mouth. **A token the rulebook names but states no readable value for is still proposed, with an empty value.** Radius steps and type sizes are prose ("Small 4px") and nothing here parses them; inventing a parse per shape would be guessing. The name is real and the value needs a human, so the proposal says exactly that — and the UI leads with the COUNT of those, because an import that hid them would look more complete than it is. Preview is the default on both surfaces and in the UI. An import is a proposal: rulebooks are written aspirationally and some of what they describe was never built, so every entry carries the rule id and the sentence it came from and a reviewer can check the claim rather than trust it. Existing token names are never overwritten. A value already in the record was put there deliberately — most likely correcting this importer — so a re-run fills gaps and lists the rest as skipped, which also makes it safe to repeat. Colours the rulebook names but never exposes as a custom property produce no token: it never asked for one, and inventing a name would put something in the record no rule sanctions.	2026-07-30 21:23:32 -04:00
bvandeusen	3da40abcb8	feat(design-systems): declare what to write instead, rather than what not to ... Milestone #254 step 6, first half (#2295) — and this reframes the task rather than answering it. The operator's call: "in this case we should declare what should be used in place of pure white, it's not a prohibition it's what should be used in its place." None of the three options on the table (a constraints record / the panel reads both sources / negative token rows) was right, because all three kept the prohibition as a KIND OF THING. It isn't one. "Pure white is never text" is the shadow cast by a positive fact — text is Parchment — and a design system that stores what things ARE has no row for a ban because it never needed one. So `design_tokens` gains `supersedes`: the literal values this token should be written instead of. `--color-text-on-action` supersedes `#fff` / `#ffffff`. Same fact as the rule, stated forwards, and now actionable — a finding can say what to write rather than only objecting. It has to be DECLARED, not derived, and that is the crux: `#fff` and Parchment `#E8E4D8` are different colours, so no value-matching check could ever have connected them. That mismatch is precisely why the prohibition looked unrepresentable until it was turned around. `supersedes` cascades on EMPTINESS rather than on None. A child overriding a colour says nothing about which literals it replaces, and blanking the family's declaration there would silently disarm the check for every app that customises the token — while a child that states its own list replaces it wholesale. Two things this deliberately does NOT do: - It does not feed the drift panel. Superseded literals live in component CSS, which `designDrift.ts` cannot see and already documents as a blind spot. This is input for the source lint (#2277). Declaring it with nothing consuming it yet is honest; wiring it to a panel that cannot check it would not be. - It does not remove the panel's `prohibited_color` arm yet — that happens when the panel is repointed at a resolved system, which needs #2288 first. The declaration also exposes a missing token: most of the 67 hardcoded `color: #fff` (#2275) are text on a coloured action button, and the system has no token for that role at all. Every view hardcodes it. Declaring the token that was never there is the first real output of the operator's framing.	2026-07-30 21:16:45 -04:00
bvandeusen	0937b1761e	feat(design-systems): the editing surface — overrides, effective set, provenance ... Milestone #254 step 5 (#2294). /design-systems is the editable half of the surface /design already showed: that page is what the browser renders, this one is the record that ought to decide it. Each links to the other. The layout follows the model rather than decorating it. Two token lists, and they are deliberately different questions: Overrides — the system's own rows. Short by design, and EMPTY is the correct state for an app that hasn't departed from its family yet, so that empty state says so rather than looking unfinished. Effective — what it resolves to with inheritance applied, each row labelled with where its value came from. Provenance renders PER MODE when the modes disagree. A system can own `base` and inherit `dark` at once — that is the case the value column is a map for — and a single badge per row would have to lie about one of them. Rows whose modes agree (the common case) keep the single badge. "Defined here" and "overridden here" are distinct labels. Introducing a token and shadowing an ancestor's are different acts, and `is_overridden_in` is already false for the first. The parent picker filters out the selected system's descendants. The server refuses those anyway with a message naming the loop — but a refusal you cannot trigger beats a refusal explained well. Cycles that arrive some other way still render a truncated chain rather than freezing the tab: the client keeps the same defensive visited-set the server has. Three drift bugs caught while writing the styles, all of the shape this milestone exists to surface: - `--color-accent` does not exist. I had used it for every focus ring and active border; it would have rendered as nothing at all, silently. The brand token is `--color-primary`. - focus rings are ALREADY global in theme.css (`button:focus-visible` et al). My per-element rules would have overridden the house ring with a different one — the exact "bypassed abstraction" shape from #253. - every existing `.btn-primary` copy uses `color: #fff`, which is rule 52's prohibition and 67 live violations (#2275). This one uses Parchment and says why in a comment, rather than becoming the 68th. Also wires the project pointer into ProjectView's details panel, hidden entirely when no design systems exist (rule #115 — that is the ordinary state, not a degraded one) and saved through its own PUT, since clearing it is a real outcome rather than an omission.	2026-07-30 17:17:43 -04:00