01
Mirror the public API
Variant and boolean properties use the same concepts and defaults as code.
Guideline 02Operational
Component construction
Figma-equivalent component anatomy, sizing, properties, slots, overrides, and design-to-code parity rules.
- Owner
- Design Systems and Frontend Platform
- Last reviewed
- August 2026
- Review cadence
- With every component API change
- Source of truth
- playground component specs and src/components
Required outcomes
01
A designer can create a supported instance without detaching it.
02
Each design property maps to a public prop, slot, or documented composition.
03
Resize, localization, and exceptional-state behavior is decided before release.
01
Asset model and naming
One component set represents one public concept. Names encode hierarchy, not visual styling.
Layer naming model
| Layer | Pattern | Example | Rule |
|---|---|---|---|
| Library asset | Component / Name | Component / Button | Matches the public export name. |
| Variant property | Sentence case | Variant = Primary | Maps to a finite prop union. |
| Boolean property | Show + noun | Show icon = True | Controls optional visibility, not layout hacks. |
| Text property | Content role | Label = Save | Exposes only content intended for instance editing. |
| Nested layer | Semantic role | Leading icon | Names responsibility rather than shape or position. |
Construction principles
02
Prefer nested components
Icons, field messages, and surfaces remain replaceable nested assets where supported.
03
Protect structural layers
Consumers may edit content and approved swaps, but should not need to unlock layout layers.
04
Document intentional gaps
Utility and provider exports are marked as code-only instead of receiving fictional canvas assets.
02
Auto layout and resizing
Each axis has an explicit contract: hug, fill, fixed, or content-controlled.
Sizing decisions
| Mode | Use when | Avoid when | Code equivalent |
|---|---|---|---|
| Hug | Content defines the useful dimension. | Peer alignment requires equal widths. | inline-flex, w-fit, intrinsic sizing |
| Fill | The parent owns available space. | The control should remain content-sized. | w-full, flex-1, min-w-0 |
| Fixed | The dimension is a tokenized target. | Localized text or user content is present. | size-* or explicit component token |
| Content-controlled | Media or a consumer slot owns proportion. | The component can define a safe default. | aspect-ratio, min/max constraints |
Resize stress test
Canvas
- Test minimum supported width.
- Test fill-container behavior.
- Test 200 percent text scaling.
- Test a three-line translated label.
- Test optional slots removed and replaced.
Code
- Verify flex children use min-width: 0 where truncation is intended.
- Verify hit targets do not shrink below 44 by 44px on touch.
- Verify overflow is documented as wrap, clip, scroll, or expand.
- Verify DOM and focus order match the visual layout.
03
Properties, slots, and overrides
Editable surfaces are intentional and finite. They should produce supported code, not arbitrary new component states.
Property strategy
01
Variants represent meaningful choice
Use a variant only when appearance and behavior form a named, supported option.
- No boolean explosion
- No duplicated state variants
- No theme property on components
02
State is demonstrated, not configured
Hover, focus, pressed, loading, invalid, and disabled are prototype or specimen states unless the API directly owns them.
03
Slots describe composition boundaries
A slot declares acceptable content, size, alignment, and fallback behavior.
04
Instance swaps stay type-safe
Limit swaps to assets that satisfy the same semantic and dimensional contract.
Override policy
| Change | Allowed | Condition |
|---|---|---|
| Text content | Yes | Within documented content limits and accessible naming rules. |
| Nested icon swap | Yes | Same icon size and semantic role. |
| Semantic color token | By variant only | No local fills or raw values. |
| Internal spacing | No | Request a supported size or composition instead. |
| Layer deletion | Boolean property only | Do not delete locked structural layers. |
| Detach instance | Exception only | Requires a documented system gap and follow-up issue. |
04
Design-to-code parity
Parity means equivalent decisions, defaults, states, and behavior. Pixel similarity alone is insufficient.
Parity review
- 01
Inventory
Owner: Designer
Anatomy, variants, content bounds, resize rules
Exit gateAll supported decisions are represented. - 02
Map
Owner: Engineer
Property-to-prop and slot-to-composition mapping
Exit gateNo design property requires an undocumented override. - 03
Stress
Owner: Design and QA
Theme, locale, zoom, keyboard, state evidence
Exit gateBoth implementations pass the same acceptance cases. - 04
Publish
Owner: Design Systems
Versioned design asset, package release, migration note
Exit gateSources publish together or the change remains unreleased.
Definition of parity
Design
- Names and defaults match code.
- All public variants and states are demonstrated.
- Auto layout reproduces responsive intent.
- Tokens are semantic aliases, not copied values.
Code
- Public props match documented properties.
- Native semantics and keyboard behavior are preserved.
- Visual regression covers both themes.
- Release notes identify additions, changes, and deprecations.