# Design System > Design System - Skill: `handsomeboy990/design-system` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add handsomeboy990/design-system` - Raw SKILL.md: https://api.skillmd.com/api/skills/handsomeboy990/design-system/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: Handsomeboy990 (https://skillmd.com/u/handsomeboy990) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/handsomeboy990/design-system --- # Design System A design system is not a component library. It is the set of decisions that make independent work look like one product, and the library is how those decisions are distributed. Built too early it constrains a product that has not found its shape. Built too late it becomes an archaeology project. The right moment is the third repetition. ## 1. Tokens Tokens are the decisions. Components consume them and never hardcode a value. ``` colour a small palette, then semantic names on top: surface, text, border, accent, danger, and their states spacing one scale, used for every margin, padding and gap typography a scale of size and line height, a small set of weights, and the families radius a scale, usually three values, not one per component elevation a small set, each with a stated meaning motion durations and easings, with a reduced motion variant breakpoints named, and used everywhere instead of raw widths z-index a named ladder, so nothing is 9999 ``` Two layers matter: the raw value, and the semantic name that points at it. Components use the semantic name, so a theme change is one indirection away. ## 2. Semantic naming ``` raw blue-600, gray-100, space-4 semantic color-action, color-surface-raised, space-inline-md component button-background, card-padding, only where a component genuinely needs its own hook ``` A component that references `blue-600` cannot be themed. A component that references `color-action` can be themed, inverted, and rebranded without being opened. ## 3. Component contract Every component in the system declares: ``` purpose what it is for, and what it is not for anatomy its parts variants the finite set, named, with no free form styling escape sizes from the scale, not arbitrary states default, hover, focus visible, active, disabled, loading, error, selected, and empty where it applies content rules what it accepts, and what happens when the content is long, short, absent or in another language accessibility role, name, keyboard behaviour, focus management composition what it may contain, and what it may sit inside props the minimum surface, with no style overrides ``` The state list is the part that separates a design system from a folder of components. A button without a focus visible style and a loading state is not finished, however good it looks. ## 4. Theming ``` themes are token sets, not component forks dark mode is a theme, defined completely, not derived by inverting contrast verified in every theme, on the rendered pairs a theme switch has a defined behaviour for images, illustrations and shadows system preference respected by default, user choice persisted and winning no component reads the theme directly: it reads tokens ``` ## 5. Composition and escape hatches ``` prefer composition over configuration: a component with fourteen boolean props is four components provide one deliberate escape hatch, documented, for genuinely one-off needs never accept an arbitrary style override as a prop, which turns the system into a suggestion when a screen needs something the system lacks, that is a system finding, not a licence to improvise: record it, then either add it or refuse it ``` ## 6. Documentation ``` each component: what it is for, when not to use it, examples of correct use, examples of incorrect use, its states rendered, its accessibility contract the tokens, rendered, with their semantic meaning the patterns above component level: forms, empty states, error states, destructive confirmations, page layouts the contribution path: how a new component or token gets in ``` A design system with no documentation on when not to use a component produces consistent misuse. ## 7. Versioning and change ``` the system is a dependency with a version, even inside a monorepo a breaking visual change is a breaking change: name it, version it, note it deprecations carry a replacement and a date a token rename ships with a codemod or an alias, never as a search and replace request to every team changes are reviewed against the existing usage, not only against the design ``` ## 8. Adoption For an existing product: ``` 1 inventory what exists: every button, every input, every card, photographed 2 the count is the argument: eleven button styles is a fact, not an opinion 3 tokens first, applied to what exists, before any component is rewritten 4 then the highest traffic components, one at a time 5 migrate on contact: a screen being changed adopts the system 6 never a rewrite of every screen at once 7 measure adoption, so the effort has an end ``` ## 9. Prohibitions - Never hardcode a colour, spacing or font size in a product screen. - Never fork a component to change one visual detail. - Never accept arbitrary style overrides through props. - Never ship a component without its focus visible, disabled and loading states. - Never define dark mode by inverting light mode. - Never let the system grow a component per screen. - Never change a token's meaning while keeping its name. - Never build the system before the third repetition of a pattern. ## 10. Protocol 1. Inventory what exists and count the variations. 2. Define the raw scales, then the semantic tokens on top. 3. Apply tokens to the existing product before writing components. 4. Define the component contract format, and write it for the first three. 5. Implement the states in full, including focus visible and loading. 6. Define themes as token sets and verify contrast in each. 7. Document purpose, misuse, states and the accessibility contract. 8. Version the system and define the deprecation path. 9. Migrate on contact, and measure adoption. 10. Review new screens against the system, and record what the system lacks. ## 11. Auto-critique Score from 0 to 5: token layering, semantic naming, completeness of the state inventory, theming without forks, composition over configuration, absence of style escape hatches, documentation including misuse, versioning and deprecation, adoption path that ends. Threshold: no axis below 3, average at least 4. A component library whose components accept arbitrary style overrides is not a design system, and it is reworked before it spreads. ## 12. Interfaces - Upstream: `ui-ux-engineering` for the experience decisions, `requirements-analysis` for the brand and platform constraints. - Lateral: `frontend-engineering` for implementation, `accessibility-testing` for the contracts, `internationalization` for logical properties and text expansion, `dependency-selection` before adopting an external library. - Downstream: `playwright-automation` for visual verification, `technical-documentation` for the published documentation, `technical-debt` for the unmigrated surface.