docs(design): keep DESIGN.md to rules that stay true - #2530
Merged
Merged
Conversation
Astro-Han
force-pushed
the
docs/design-trim-2.0-spec
branch
from
August 8, 2026 18:51
4964492 to
f074664
Compare
Astro-Han
force-pushed
the
docs/design-trim-2.0-spec
branch
from
August 9, 2026 01:13
ec56526 to
5095e93
Compare
Astro-Han
force-pushed
the
docs/design-trim-2.0-spec
branch
4 times, most recently
from
August 9, 2026 02:42
426708e to
b6e20ee
Compare
DESIGN.md is read by agents as much as by people, so a line that has gone stale is worse than a line that was never written — it gets adopted as fact. Two kinds of line in this file cannot stay true, and both are removed here. FIRST: prose that describes the current state of the migration. - §3's One Colorspace exception, "until T4 unified it" - §4's --ring-soft, "was called --shadow-minimal-flat until T4" - §5's Floating Recipe, "currently enforced ... a transitional implementation" - §11's wash ban, "T4 migrated fourteen such sites ... the rest are debt" - §3's link rule, "--link currently resolves to raw --accent" This branch is its own evidence for why. An earlier revision of it documented the srgb exception, the shadow-minimal-flat rename and the unenforced Floating Recipe as open items; #2536 closed all three the same day, and every one of those lines had to be rewritten before this could land. A spec that tracks progress has to be rebased against progress. The rules themselves are unchanged and read stronger without the timestamps: the ladder derives in one space, --ring-soft is a border, the recipe binds every portal including Astryx's own. Where a rule and the code genuinely disagree, that belongs in an issue, not in a clause hedging the rule. SECOND: values and inventories that source already owns. - The surface pixel table and the ink contrast columns. Their caption claimed the contract tests held them; ink-ladder-contract pins two structural invariants and no number. - The seven-alias legacy surface list, which the file's own last Don't forbids copying in. Its one load-bearing fact — --background is the card fill, not the page color — moves into §2's opening sentence. Frontmatter stays. It is the machine-readable half of the DESIGN.md convention, and its consumer is the agent reading it rather than a build script, so the fix for a wrong entry is to correct it, not to delete the block. And the assertions that were simply wrong: - The radius table listed a 4px inner tier and a 16px page tier. Neither exists: --radius-inner resolves to 6px and --radius-page to 28px. Removed from the table and from the frontmatter. What replaces them is the relationship those rows were hiding — control/card/container are the same numbers as Astryx inner/element/container — now an Astryx column plus the Two-Name Rule, which says the pairs agree today as independent literals and can still be split by an upstream bump. - "There is no info status semantic" fused the color families with the dot semantics. --info is live in eleven palettes; what has no info is StatusSemantic. Read as written it told the next reader to delete a token the source deliberately keeps. Split across §8 and §9. - Astryx's Badge and StatusDot carry fixed literals from the neutral theme, so an Astryx info pill and Maka's --info are unrelated blues. Recorded. - Astryx's Text color="secondary" is not this ladder's secondary: it reads --color-text-secondary, a fixed literal outside the bridged containers and --muted-foreground inside them. Three results for one word, with live call sites on both sides. - §1 said maka-tokens.css owns "the Astryx bridge". It owns one third of it. - §7 listed Heading 1-5, omitting heading-6 and large. - §4's --border-strong and §9's scrollbar thumb contradicted each other. Reconciled on §9's side, since T5 shipped the thumb. 248 -> 238 lines. Doc-only; no token or product CSS changes.
Astro-Han
force-pushed
the
docs/design-trim-2.0-spec
branch
from
August 9, 2026 04:14
b6e20ee to
ecb5327
Compare
Astro-Han
marked this pull request as ready for review
August 9, 2026 06:00
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DESIGN.md is read by agents as much as by people, so a stale line is worse than a missing one — it gets adopted as fact. This removes the two kinds of line that cannot stay true, and fixes the assertions that were already wrong. Doc-only: no token or product CSS changes. 248 → 238 lines.
1. Prose that tracks the migration's current state
Removed from §3, §4, §5 and §11:
--ring-soft, "was called--shadow-minimal-flatuntil T4"--linkcurrently resolves to raw--accent"This branch is its own evidence for why. An earlier revision of it documented the srgb exception, the
--shadow-minimal-flatrename and the unenforced Floating Recipe as open items. #2536 closed all three the same day, and every one of those lines had to be rewritten before this could land. A spec that tracks progress has to be rebased against progress.The rules are unchanged and read stronger without the timestamps: the ladder derives in one space,
--ring-softis a border, the recipe binds every portal including Astryx's own. Where a rule and the code genuinely disagree, that belongs in an issue rather than in a clause hedging the rule.2. Values and inventories that source already owns
ink-ladder-contractpins two structural invariants and no number.--backgroundis the card fill, not the page color — moves into §2's opening sentence.Frontmatter stays. It is the machine-readable half of the DESIGN.md convention and its consumer is the agent reading it, not a build script, so a wrong entry gets corrected rather than deleted.
3. Assertions that were wrong
innerand 16pxpagetiers--radius-innerresolves to 6px,--radius-pageto 28px. Removed from table and frontmattercontrol/card/containerare the same numbers as Astryxinner/element/container. New Astryx column + Two-Name Rule, which notes the pairs agree today as independent literals and can still be split upstream--infois live in eleven palettes; what has noinfoisStatusSemantic. Split across §8 and §9BadgeandStatusDotcarry fixed neutral-theme literals, so an Astryxinfopill and Maka's--infoare unrelated bluesText color="secondary"reads--color-text-secondary— a fixed literal outside the bridged containers,--muted-foregroundinside. Three results for one word, live call sites on both sidesmaka-tokens.cssowns "the Astryx bridge"makaTheme.tsandastryx-mount.cssown the restheading-6andlargeare real roles and were missing--border-strong"no fills" vs scrollbar thumb using it as a fillVerification
npm run format:checkgreen; diff touches DESIGN.md only.expandRadiusScale.js, generatedmaka.css,astryx.cssatomic classes,maka-tokens.css,astryx-mount.css,packages/ui/src/status-vocabulary.ts.main(post-T5).Related: #2525 (T1), #2536 (T2–T4), #2538 (T5), task #168.