Three tweaks · 66 → 94
so you get a present.
## Design system rules
<!-- Generated by roast-my-design-system from a scan of adobe/spectrum-web-components on 2026-09-01.
Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:
npx roast-my-design-system@latest --rules -->
Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.
### Colours and tokens
- This system's tokens answer to the `--spectrum-*` namespace. Reach for an existing `var(--...)` from them before inventing any value.
- `--swc-*`, `--mod-*`, `--system-*` are also present in the code. Before writing new references to them, check whether this repo treats them as current or as a migration source; when unsure, prefer `--spectrum-*`.
- Design tokens live in `1st-gen/tools/styles/tokens/index.css`. Reach for an existing token before inventing any value.
- Never hardcode colour values in components. The palette already has 1302 tokens; the scan still found 56 hardcoded colours sitting next to them. Do not add more.
- Never eyeball a colour from memory: the scan found 5 nearly identical pairs (like #f5f5f5 next to #f8f8f8). Look the exact value up, or better, use its token.
### Canonical components
- Use these existing components instead of writing new ones, the way this repo already uses them:
- `<BreadcrumbItem>` from `1st-gen/packages/breadcrumbs/sp-breadcrumb-item.ts` (used 7x)
- `<InfieldButton>` from `1st-gen/packages/infield-button/sp-infield-button.ts` (used 3x)
- `<Theme>` from `1st-gen/tools/theme/sp-theme.ts` (used 3x)
- `<Combobox>` from `1st-gen/packages/combobox/sp-combobox.ts` (used 2x)
- `<Breadcrumbs>` from `1st-gen/packages/breadcrumbs/sp-breadcrumbs.ts` (used 1x)
- `<ColorField>` from `1st-gen/packages/color-field/sp-color-field.ts` (used 1x)
- `<ContextualHelp>` from `1st-gen/packages/contextual-help/sp-contextual-help.ts` (used 1x)
- `<CssTable>` from `1st-gen/projects/css-custom-vars-viewer/src/sp-css-table.ts` (used 1x)
### Spacing and sizing
- Avoid new one-off CSS spacing values; 26 off-scale values are already in play.
### Typography
- The repo uses 20 typefaces: token("sans-serif-font"), token("serif-font"), Adobe Clean, Adobe Clean Serif. Do not introduce another, and do not re-declare font stacks by hand; use the existing setup.
### Styling discipline
- Never write `style={{ ... }}` for static values; styling belongs to classes and tokens where the system can see it.
- Never write !important; the scan found 40 declarations already. When a style does not apply, fix the selector or the source of the conflict instead of shouting over it.
- Before styling anything new, look at a neighbouring component and match how it does it. Consistency with the repo beats personal preference.
---
*Generated by [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system) ver. 5.7.2. Rescan after refactors to keep these rules honest.*
2 packages with enough UI to judge · the repo score above is the whole thing blended, and 90 packages were too small or too backend to score
| package | score | worst finding | size |
|---|---|---|---|
| 2nd-gen/packages/swc | 90 | 27 !important declarations | 176 files |
| 1st-gen/tools/styles | 95 | 1 !important declarations | 7 files |
A repo scores below its own packages by arithmetic, not by accident: distinct values add up across packages, so the whole always carries more than any part. Read the package scores for where each team stands, and the repo score for what your agent sees when it looks at everything at once.
Your agent reads AGENTS.md, .cursor/rules. But none of it points at a single source of truth for components and tokens, because there isn't one yet. The numbers below are what your agent actually works from.
Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.
A healthy product palette is up to ~24 colours: one brand hue with a few tints, one accent, up to 13 greys, and status colours.
a disciplined repo keeps these around a dozen · on-scale Tailwind steps (·) shown for context · off-scale in coral
every distinct declaration is a chance for the next one to be wrong
the 5 files carrying the most off-system styling
styling no system can see
68 components defined · tile area is internal use: how the system builds from itself, downstream consumers invisible from here · the real system, drawn to scale
6 components are imported exactly once: <Breadcrumbs>, <ColorField>, <ContextualHelp>, <CssTable>, <OnionSkinner>, <StoryDecorator>. Quiet corners, not yet a system.
| component | used | defined in | props |
|---|---|---|---|
| <BreadcrumbItem> | 7× | 1st-gen/packages/breadcrumbs/sp-breadcrumb-item.ts | none |
| <InfieldButton> | 3× | 1st-gen/packages/infield-button/sp-infield-button.ts | none |
| <Theme> | 3× | 1st-gen/tools/theme/sp-theme.ts | none |
| <Combobox> | 2× | 1st-gen/packages/combobox/sp-combobox.ts | none |
| <Breadcrumbs> | 1× | 1st-gen/packages/breadcrumbs/sp-breadcrumbs.ts | none |
| <ColorField> | 1× | 1st-gen/packages/color-field/sp-color-field.ts | none |
| <ContextualHelp> | 1× | 1st-gen/packages/contextual-help/sp-contextual-help.ts | none |
| <CssTable> | 1× | 1st-gen/projects/css-custom-vars-viewer/src/sp-css-table.ts | none |
| <OnionSkinner> | 1× | 1st-gen/projects/vrt-compare/onion-skinner.ts | none |
| <StoryDecorator> | 1× | 1st-gen/projects/story-decorator/sp-story-decorator.ts | none |