Every variant of every primitive
Visual contract for the four design-system primitives: Button, Chip, Surface, MetadataRow. Spot regressions at a glance. Reference the examples below before introducing a new variant — if the existing variants don’t fit, the design is wrong, not the system.
See docs/DESIGN-SYSTEM.md for the written canon.
Button
Closed enum: intent (forge / ai / outline / ghost / danger) × size (xs / sm / md / lg). B1905 added ghost + danger + xs.
Intent variants (size: md)
Sizes (intent: forge)
With leading icon
Loading + disabled
As link (renders <a> via href)
Chip
10 variants × 2 sizes. The on-image variant lives over varying-tone backgrounds.
Variants (size: xs)
Variants (size: sm)
With leading icon
Clickable (with onClick)
On-image (over a varying-tone backdrop)
Surface
Three kinds: card / quiet / code.
kind="card" (default padding lg)
Card surface
Default panel — same rendering as className="card" under the hood. Use this for primary content blocks.
kind="quiet" (diagnostic / metadata)
Quiet surface — softer background + softer border. Use inside a card for sub-sections (diagnostic readouts, metadata grids).
kind="code" (CLI / install snippets)
$ npm install @songforgeai/scoring-rubric $ npx sfai verify song.json
MetadataRow
Wraps "flex flex-wrap gap-1.5 items-center" with align/spacing props.
align="center-mobile" (default)
align="start" (no md-only flip)
NextActionPair
The unified primary + secondary action pair every primary surface ends with. One forge-orange CTA + one ghost alternate, side-by-side at md+, stacked on mobile.
Standard primary + secondary
alignEnd: justify-end on desktop
FooterLadder
Continue / adjacent-surfaces section that ships at the bottom of long content pages. 2-4 link cards (3 recommended), each with a label + optional body + optional icon.
TrustBlock
A claim + its proof, paired. Ships across /the-receipts, /scoring/standard, /about. The icon → headline → proof → optional sub-link rhythm is canonical.
Three trust blocks (different tones)
ed25519 seal embedded in every API response. Verify any score against the published pubkey.
Verify a score →Lyric Scoring Standard v1.3 published under CC BY 4.0. Same definitions any third party scores against.
Read the standard →Postmortem within the same week of every user-visible incident. Plainly worded. Root cause + prevention.
Read incidents →