Skip to content

docs(design): keep DESIGN.md to rules that stay true - #2530

Merged
Astro-Han merged 1 commit into
mainfrom
docs/design-trim-2.0-spec
Aug 9, 2026
Merged

Astro-Han merged 1 commit into
mainfrom
docs/design-trim-2.0-spec

Conversation

@Astro-Han

@Astro-Han Astro-Han commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

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:

  • the One Colorspace exception, "until T4 unified it"
  • --ring-soft, "was called --shadow-minimal-flat until T4"
  • the Floating Recipe, "currently enforced … a transitional implementation"
  • the wash ban, "T4 migrated fourteen such sites … the rest are debt"
  • the 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 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 rather than in a clause hedging the rule.

2. 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 this 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, not a build script, so a wrong entry gets corrected rather than deleted.

3. Assertions that were wrong

Where Was Is
§6 4px inner and 16px page tiers Neither exists — --radius-inner resolves to 6px, --radius-page to 28px. Removed from table and frontmatter
§6 The relationship those rows hid: control/card/container are the same numbers as Astryx inner/element/container. New Astryx column + Two-Name Rule, which notes the pairs agree today as independent literals and can still be split upstream
§8 "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. Split across §8 and §9
§8/§9 Astryx Badge and StatusDot carry fixed neutral-theme literals, so an Astryx info pill and Maka's --info are unrelated blues
§3 Astryx's Text color="secondary" reads --color-text-secondary — a fixed literal outside the bridged containers, --muted-foreground inside. Three results for one word, live call sites on both sides
§1 maka-tokens.css owns "the Astryx bridge" It owns one third; makaTheme.ts and astryx-mount.css own the rest
§7 Heading 1–5 heading-6 and large are real roles and were missing
§4/§9 --border-strong "no fills" vs scrollbar thumb using it as a fill Reconciled on §9's side, since T5 shipped the thumb

Verification

  • npm run format:check green; diff touches DESIGN.md only.
  • Every claim checked against source: expandRadiusScale.js, generated maka.css, astryx.css atomic classes, maka-tokens.css, astryx-mount.css, packages/ui/src/status-vocabulary.ts.
  • Rebased onto current main (post-T5).

Related: #2525 (T1), #2536 (T2–T4), #2538 (T5), task #168.

@Astro-Han
Astro-Han force-pushed the docs/design-trim-2.0-spec branch from 4964492 to f074664 Compare August 8, 2026 18:51
@Astro-Han
Astro-Han force-pushed the docs/design-trim-2.0-spec branch from ec56526 to 5095e93 Compare August 9, 2026 01:13
@Astro-Han Astro-Han changed the title docs(design): trim the 2.0 spec to rulings, fix the button radius contradiction docs(design): trim the 2.0 spec to rulings and fix what source contradicts Aug 9, 2026
@Astro-Han
Astro-Han force-pushed the docs/design-trim-2.0-spec branch 4 times, most recently from 426708e to b6e20ee Compare August 9, 2026 02:42
@Astro-Han Astro-Han changed the title docs(design): trim the 2.0 spec to rulings and fix what source contradicts docs(design): keep DESIGN.md to rules that stay true Aug 9, 2026
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
Astro-Han force-pushed the docs/design-trim-2.0-spec branch from b6e20ee to ecb5327 Compare August 9, 2026 04:14
@Astro-Han
Astro-Han marked this pull request as ready for review August 9, 2026 06:00
@Astro-Han
Astro-Han merged commit 07fb155 into main Aug 9, 2026
11 checks passed
@Astro-Han
Astro-Han deleted the docs/design-trim-2.0-spec branch August 9, 2026 06:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant