In progress
Open Figma file Live state notes

Documentation site · interactive previews · Light/Dark theme · synced 2026-07-17

Fukurou Design System

Fukurou Design System is a scalable component and token system for building consistent, accessible product experiences.

System
Fukurou Design System
Status
In progress
Themes
Light / Dark
Token model
3-tier + Density + Layout
Accessibility
WCAG audit tracked
Source of truth
Live Figma file

Who it’s for

Designers

Use the Figma library for components, variants, and theme modes. Prefer published public sets over internal .Base pieces.

Engineers

Map to the token tiers (Foundation → Theme → Component). Mirror Active vs Focus Visible on form controls. Do not invent missing components.

Stakeholders

Track status, accessibility posture, and what is intentionally not in the system yet.

Core principles

  • Tokens first — color and spacing decisions flow Foundation → Theme → Component.
  • Accessible by default — text contrast, focus indicators, and non-color cues are required.
  • Public vs internal — consumers use public sets; .Base / helper components stay nested.
  • Figma is source of truth — if docs and Figma disagree, inspect the live file before changing product code.

How to use this documentation

  1. Start with Foundations and Tokens for architecture.
  2. Open a component section for purpose, states, and HTML previews.
  3. Check Accessibility before shipping.
  4. Confirm the live component in Figma via CURRENT_FIGMA_STATE.md.

Live snapshot (2026-07-17): ~627 variables · 19 public component sets · WCAG audit 408 pairs · 0 non-exempt failures · brand #D33F55 / #231F20.

Foundations

Foundations are the raw ingredients of the system: brand ramps, type, space, radius, elevation, density, and layout modes.

Foundation

Color

Foundation colors are raw palette values in 1. Foundation. Ramps are generated from the brand colors: tints for 50–400, the brand value at 500, and shades for 600–900. Every swatch is a primitive variable.

Brand

Core brand anchors — do not change casually; Theme and Component tokens depend on them.

Primary
color/brand/primary/500 #D33F55
Secondary
color/brand/secondary/500 #231F20

Primary

Brand · #D33F55

50 color/brand/primary/50 #FDF5F6
100 color/brand/primary/100 #F9E4E7
200 color/brand/primary/200 #F2C5CC
300 color/brand/primary/300 #E99FAA
400 color/brand/primary/400 #DE7181
500 color/brand/primary/500 #D33F55
600 color/brand/primary/600 #AD3446
700 color/brand/primary/700 #872836
800 color/brand/primary/800 #651E29
900 color/brand/primary/900 #48151D

Secondary

Brand · #231F20

50 color/brand/secondary/50 #F4F4F4
100 color/brand/secondary/100 #E0E0E0
200 color/brand/secondary/200 #BDBCBC
300 color/brand/secondary/300 #918F8F
400 color/brand/secondary/400 #5C595A
500 color/brand/secondary/500 #231F20
600 color/brand/secondary/600 #1D191A
700 color/brand/secondary/700 #161414
800 color/brand/secondary/800 #110F0F
900 color/brand/secondary/900 #0C0B0B

Neutral

UI grays · includes 0 and 1000

0 color/neutral/0 #FFFFFF
50 color/neutral/50 #FAFAF9
100 color/neutral/100 #F5F5F4
200 color/neutral/200 #E7E5E4
300 color/neutral/300 #D6D3D1
400 color/neutral/400 #A8A29E
500 color/neutral/500 #78716C
600 color/neutral/600 #57534E
700 color/neutral/700 #44403C
800 color/neutral/800 #292524
900 color/neutral/900 #1C1917
1000 color/neutral/1000 #000000

Amber

Warning / caution primitives

50 color/amber/50 #FDF8F3
100 color/amber/100 #FAECDC
200 color/amber/200 #F4D6B4
300 color/amber/300 #ECBB82
400 color/amber/400 #E39A47
500 color/amber/500 #D97706
600 color/amber/600 #B26205
700 color/amber/700 #8B4C04
800 color/amber/800 #683903
900 color/amber/900 #4A2802

Red

Danger / error primitives

50 color/red/50 #FDF4F4
100 color/red/100 #FAE1E1
200 color/red/200 #F4BEBE
300 color/red/300 #ED9292
400 color/red/400 #E55E5E
500 color/red/500 #DC2626
600 color/red/600 #B41F1F
700 color/red/700 #8D1818
800 color/red/800 #6A1212
900 color/red/900 #4B0D0D

Green

Success primitives · 200 & 800 present

50 color/green/50 #F1F8F4
100 color/green/100 #D8ECDF
200 color/green/200 #ACDABD
300 color/green/300 #7FC89B
400 color/green/400 #4CAF76
500 color/green/500 #2F9E60
600 color/green/600 #25804E
700 color/green/700 #1C6B41
800 color/green/800 #145331
900 color/green/900 #0D3A22

Blue

Info primitives · 200 & 800 present

50 color/blue/50 #EEF4FD
100 color/blue/100 #D6E6FB
200 color/blue/200 #B9D3F6
300 color/blue/300 #9CC0F2
400 color/blue/400 #5F97E6
500 color/blue/500 #3F86E0
600 color/blue/600 #2F6FC4
700 color/blue/700 #1D4A8A
800 color/blue/800 #183A6D
900 color/blue/900 #122A4F

Status mapping

Foundation ramps feed status meaning through Theme — prefer semantic tokens in product UI.

Status Foundation ramp Typical base (500/600) Use via
Success color/green/* #2F9E60 color/status/success/*
Warning color/amber/* #D97706 color/status/warning/*
Danger / Error color/red/* #DC2626 color/status/danger/*
Info color/blue/* #3F86E0 color/status/info/*

Usage guidance

  • Foundation colors are raw palette values — no product meaning by themselves.
  • Prefer Theme / semantic tokens for surfaces, text, borders, and actions in product UI.
  • Component fills and strokes should come from Component tokens that alias through Theme.
  • Do not hard-code Foundation hex values in components unless intentionally documenting or building the palette itself.
  • Brand primary/secondary should not be changed casually — Theme and Component tokens depend on them.

Theme note: In the live file, color/action/primary/* resolves to neutral black/white. Brand red accent is on color/action/tertiary/* and Progress Bar fill. Do not assume Action buttons are brand red without checking Theme.

Foundation

Typography

Lora (serif) for display and headings; Poppins (sans) for body, captions, and buttons. The library ships 18 local text styles.

Font families

Lora

Header / display
Lora · SemiBold

Used for display/* and heading/* styles. Establishes brand voice and page hierarchy.

Poppins

Body / UI
Poppins · Regular / SemiBold

Used for body/*, caption/*, button/*, and text-button/*. Optimized for product UI readability.

Specimens

Live previews using the same sample string as the Figma Foundations frame.

display/lgLora SemiBold · 56 / 64

Build once, theme anywhere

heading/xlLora SemiBold · 40 / 48

Build once, theme anywhere

heading/mdLora SemiBold · 24 / 32

Build once, theme anywhere

body/mdPoppins Regular · 16 / 24

Build once, theme anywhere

caption/mdPoppins Regular · 12 / 16

Build once, theme anywhere

button/mdPoppins SemiBold · 14 / 20

Build once, theme anywhere

Type scale

All 18 local text styles from the live file, grouped by role. Sizes and line heights are the published Figma values; letter spacing is 0% across the set.

Display & Heading

Lora SemiBold — brand voice and page hierarchy.

  • Build once

    display/lg

    Hero / marketing display

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    56 / 64
    Tracking
    0%
    Decoration
    None

  • Build once

    display/md

    Large display titles

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    48 / 56
    Tracking
    0%
    Decoration
    None

  • Design with clarity

    heading/xl

    Page titles

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    40 / 48
    Tracking
    0%
    Decoration
    None

  • Design with clarity

    heading/lg

    Section titles

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    32 / 40
    Tracking
    0%
    Decoration
    None

  • Design with clarity

    heading/md

    Subsection titles

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    24 / 32
    Tracking
    0%
    Decoration
    None

  • Design with clarity

    heading/sm

    Card and panel titles

    Family
    Lora
    Weight
    SemiBold · 600
    Size / LH
    20 / 28
    Tracking
    0%
    Decoration
    None
Body & Caption

Poppins Regular — product copy and supporting text.

  • Fukurou helps teams build consistent product experiences.

    body/lg

    Lead paragraphs

    Family
    Poppins
    Weight
    Regular · 400
    Size / LH
    18 / 28
    Tracking
    0%
    Decoration
    None

  • Fukurou helps teams build consistent product experiences.

    body/md

    Default product body copy

    Family
    Poppins
    Weight
    Regular · 400
    Size / LH
    16 / 24
    Tracking
    0%
    Decoration
    None

  • Fukurou helps teams build consistent product experiences.

    body/sm

    Compact body / dense UI

    Family
    Poppins
    Weight
    Regular · 400
    Size / LH
    14 / 20
    Tracking
    0%
    Decoration
    None

  • Helper text and metadata

    caption/md

    Helper text, metadata

    Family
    Poppins
    Weight
    Regular · 400
    Size / LH
    12 / 16
    Tracking
    0%
    Decoration
    None

  • Helper text and metadata

    caption/sm

    Secondary captions / dense meta

    Family
    Poppins
    Weight
    Regular · 400
    Size / LH
    12 / 16
    Tracking
    0%
    Decoration
    None
Button & Text Button

Poppins SemiBold — action labels; underline styles are the Text Button hover state.

  • Button label

    button/md

    Button labels

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    14 / 20
    Tracking
    0%
    Decoration
    None

  • Learn more

    text-button/lg

    Large text-button labels

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    18 / 28
    Tracking
    0%
    Decoration
    None

  • Learn more

    text-button/md

    Medium text-button labels

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    16 / 20
    Tracking
    0%
    Decoration
    None

  • Learn more

    text-button/sm

    Small text-button labels

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    14 / 20
    Tracking
    0%
    Decoration
    None

  • Learn more

    text-button/underline/lg

    Large text-button hover

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    18 / 28
    Tracking
    0%
    Decoration
    Underline

  • Learn more

    text-button/underline/md

    Medium text-button hover

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    16 / 20
    Tracking
    0%
    Decoration
    Underline

  • Learn more

    text-button/underline/sm

    Small text-button hover

    Family
    Poppins
    Weight
    SemiBold · 600
    Size / LH
    14 / 20
    Tracking
    0%
    Decoration
    Underline

Note: The Foundations frame labels caption/sm as “Poppins · 11 / 16”, but the published local text style resolves to 12 / 16 (same metrics as caption/md). Docs follow the published text style.

Usage guidance

  • Use display and heading styles for page and section hierarchy (Lora).
  • Use body styles for readable product content (Poppins Regular).
  • Use button / text-button styles for actions and compact UI labels.
  • Use caption styles for helper text, metadata, and secondary details.
  • Prefer applying text styles instead of manually overriding size, weight, or line height.
  • Do not detach text from styles for one-off sizing unless intentionally documented.

Accessibility guidance

  • Keep comfortable line height — Fukurou styles pair size with explicit pixel line heights.
  • Avoid relying on text smaller than caption for critical information.
  • Maintain hierarchy with style roles, not weight alone.
  • Handle contrast through Theme color tokens, not one-off text colors.
  • Avoid all-caps for long passages; Fukurou text styles use ORIGINAL case.

Foundation

Elevation & Shadow

Inspired by the restrained depth of Vercel, the practical elevation hierarchy of Atlassian, and the tokenized component mapping approach of Polaris — adapted to Fukurou.

Use subtle shadows for everyday surfaces. Stronger shadows only for floating UI. In Dark mode, combine shadow with surface elevation color and border contrast.

Elevation scale

Seven semantic levels in 2. Theme (elevation/*) alias the effect/shadow/* primitives in 1. Foundation; each has a matching Elevation / * effect style. Every layer is offset x 0, spread 0, colour #231F20 (brand/secondary/500).

  1. None
    elevation/noneElevation / None · effect/shadow/none

    none

    Buttons, Text Fields, Icon Buttons and other flat controls.

  2. Surface
    elevation/surfaceElevation / Surface · effect/shadow/50

    0 1px 2px rgba(35, 31, 32, 0.06)

    Resting cards and everyday surfaces — one layer, barely lifted.

  3. Raised
    elevation/raisedElevation / Raised · effect/shadow/100

    0 1px 3px rgba(35, 31, 32, 0.08),
    0 1px 2px rgba(35, 31, 32, 0.04)

    Card hover — a slightly stronger lift without leaving the page plane.

  4. Floating
    elevation/floatingElevation / Floating · effect/shadow/200

    0 4px 8px rgba(35, 31, 32, 0.08),
    0 2px 4px rgba(35, 31, 32, 0.04)

    Toasts, snackbars, tooltips and selected cards.

  5. Popover
    elevation/popoverElevation / Popover · effect/shadow/300

    0 8px 16px rgba(35, 31, 32, 0.10),
    0 4px 8px rgba(35, 31, 32, 0.06)

    Dropdowns, popovers and the calendar.

  6. Modal
    elevation/modalElevation / Modal · effect/shadow/400

    0 16px 32px rgba(35, 31, 32, 0.12),
    0 8px 16px rgba(35, 31, 32, 0.08)

    Modal dialogs over a scrim.

  7. Overlay
    elevation/overlayElevation / Overlay · effect/shadow/500

    0 24px 48px rgba(35, 31, 32, 0.14),
    0 12px 24px rgba(35, 31, 32, 0.10)

    Reserved for the highest temporary layers; no component alias uses it yet.

Component mapping

Component tokens in 3. Component alias one semantic level each, so a component never picks a raw shadow.

ComponentComponent tokenElevation
Card defaultelevation/card/defaultelevation/surface
Card hoverelevation/card/hoverelevation/raised
Card selectedelevation/card/selectedelevation/floating
Dropdown / Popover / Calendarelevation/dropdown|popover|calendar/defaultelevation/popover
Modalelevation/modal/defaultelevation/modal
Toast / Snackbar / Tooltipelevation/toast|snackbar|tooltip/defaultelevation/floating
Button / Text Field / Icon Buttonelevation/button/* · elevation/text-field/*elevation/none

Dark mode

The elevation/* tokens resolve to the same shadows in Light and Dark — Figma defines no dark variants. Shadows alone are insufficient on dark surfaces, so pair them with these Theme colours.

color/surface/floating #FFFFFF · #44403C — floating panels
color/surface/elevated #FFFFFF · #292524 — raised surfaces
color/border/elevated #E7E5E4 · #57534E — edge contrast
color/surface/overlay #000 55% · #FFF 50% — scrim

Floating panel example: surface/floating fill + 1px border/elevated + elevation/floating. Toggle the theme to compare — in Dark the surface step and border carry the hierarchy while the shadow stays subtle.

Usage guidance

  • Use surface for resting cards and raised for their hover — low elevation separates surfaces without competing with content.
  • Use floating for toasts, snackbars and tooltips; popover for dropdowns, popovers and the calendar.
  • Reserve modal and overlay for temporary layers above a scrim; use them sparingly.
  • Keep elevation consistent per component by aliasing the component token, never a raw effect/shadow/* value.
  • In Dark mode, lean on surface/elevated, surface/floating and border/elevated; keep the shadow styles subtle.

Accessibility: do not rely on shadow alone for interactivity or hierarchy — use focus rings, layout, and labels. Every preview above is labelled with its level name and token.

Needs verification: the docs-site chrome and several component examples still use the older --shadow-raised / --shadow-floating / --shadow-modal / --shadow-popover variables, whose values (and heavier Dark variants) predate this scale. Card already uses elevation/card/*; the rest should be reconciled component by component.

Spacing, radius, elevation

Foundation geometry tokens (representative)
Token familyExamplesUse
spacing/*4, 8, 12, 16, 24…Gaps, padding between layers
radius/*8, 10, 12, fullInputs, cards, pills
border/width/*sm, mdControl borders, focus rings
shadow/* + elevation stylesSurface, Raised, Floating, ModalCards, snackbars, overlays

Density & layout

  • 2. Density — Comfortable · Compact · Spacious (component heights and paddings).
  • 2. Layout — Mobile · Tablet · Desktop · Wide (responsive reference values).
  • Light / Dark — modes on 2. Theme; component tokens alias through Theme.

Tokens

Fukurou uses a 3-tier token model so product teams can retheme without rewriting components.

1. Foundation

Raw values: brand/neutral/status ramps, spacing, radius, shadow primitives. No product meaning.

2. Theme

Semantic decisions with Light/Dark: surface, text, border, action, status, elevation aliases.

3. Component

Component-specific hooks such as color/button/*, color/text-field/*, color/progress-bar/*.

Supporting collections: 2. Density and 2. Layout. Collection names must stay as numbered in Figma — do not rename to Primitive/Semantic.

Sample token table

Token Light (approx.) Role
color/brand/primary/500 #D33F55 Foundation brand primary
color/surface/page #FAFAF9 Page background
color/text/default #231F20 Primary text
color/action/primary/default #000000 Primary action fill (live Theme)
color/action/tertiary/default #D33F55 Brand accent action
color/border/focus #D33F55 Focus ring stroke
color/progress-bar/fill/background/default #D33F55 Progress fill

Resolved export lives in scripts/tokens.json (510 colors as of last patch; live file reported 511). Prefer live Figma resolve when values matter for shipping.

Components

Public components from the live Fukurou library. Previews below are sized and styled from live Figma measurements and Theme tokens, with simple interactions for docs exploration. Product implementations should still ship from Figma + tokens.

ButtonAction · Secondary · Ghost Text ButtonSeparate from Button Icon ButtonGeneric icon control Notification ButtonBadge · Dot · Count CardContent grouping Text FieldActive + Focus Ring Search FieldSearch-specific input Date PickerSingle date DropdownSingle select Radio SelectorMutually exclusive CheckboxIndependent selection Toggle / SwitchOn / off settings Jumbo Select ButtonSelectable option card SnackbarTemporary feedback Alert / BannerPersistent notice TooltipShort contextual help Modal / DialogBlocking tasks PaginationDesktop + Mobile Progress BarCompletion progress

Not in the live Figma file: Textarea, Tabs, and Tag / Chip. Not current: Multi-Select Dropdown, Date Range Picker. Treat them as absent. Do not invent variants from older templates.

Button

Public

Triggers important actions. Types: Action · Secondary · Ghost. Sizes: Small (32) · Medium (40) · Large (48). Pill radius; Poppins SemiBold 14.

Variants & states

  • Type: Action · Secondary · Ghost
  • Size: Small · Medium · Large
  • State: Default · Hover · Pressed · Focus · Disabled
Interactive preview

Tokens

  • Color: color/button/*. Action aliases color/action/primary/*; Secondary and Ghost alias color/action/secondary/*.
  • Ghost: 2px border.

State behavior

  • Focus Visible: Keyboard focus (:focus-visible) shows the Figma focus-ring wrapper — 2px gap (color/button/focus/gap = surface/page) plus a 2px ring (color/button/focus/ring = border/focus) outside the body. Tab any button to see it live; the “Focus (static)” examples pin it for reference.
  • Disabled: Native disabled attribute and 60% opacity per Figma. Exempt from contrast.

Text Button

Public

Separate from Button — text-only action with no container. Sizes: Small (14/20) · Medium (16/20) · Large (18/28). Underline appears on hover only. Do not model as a Button type.

Variants & states

  • Size: Small · Medium · Large
  • State: Default · Hover · Pressed · Focus · Disabled
Interactive preview

Tokens

  • Color: color/text-button/content/* (aliases color/action/tertiary/*). Backgrounds are transparent in every state.
  • Typography: typography/text-button/sm|md|lg — Poppins SemiBold 600, 14/20 · 16/20 · 18/28, tracking 0. Weight never changes between states.

State behavior

  • Hover: text-button/underline/* — same SemiBold weight plus underline, colour content/hover.
  • Focus Visible: :focus-visible draws a 2px outside stroke (color/text-button/border/focus = border/focus) with square corners and no gap.
  • Disabled: Native disabled, content/disabled at 60% opacity. Exempt / Disabled state.

Accessibility

  • Use <a> instead of <button> when the action navigates.

Icon Button

Public

Generic circular icon-only control — Small (32×32) only, 16px icon or 12px number. Content: Icon or Number. Always provide an accessible name.

Variants & states

  • Content: Icon · Number
  • State: Default · Hover · Pressed · Focus · Disabled
Interactive preview

Tokens

  • Color: color/icon-button/* — content action/tertiary/*, hover fill action/primary/subtle, pressed fill action/primary/default with text/inverse content.

State behavior

  • Focus Visible: :focus-visible shows the offset ring — 2px gap (icon-button/focus/gap) plus a 2px ring (icon-button/focus/ring) outside the circle, not clipped.
  • Disabled: Native disabled at 60% opacity. Exempt / Disabled state.

Accessibility

  • Use a real <button> with aria-label. Icons are aria-hidden.
  • Snackbar, Alert, and Modal close controls keep their own composed-component icon colour.

Notification Button

Public

Specialized Icon Button for notifications — same 32px circle, states and focus ring, with a fixed 20px filled bell. Badge: None · Dot · Count (99+). Badge must not be the only signal of critical information.

Variants & states

  • Badge: None · Dot · Count
  • State: Default · Hover · Pressed · Focus · Disabled
Interactive preview

Tokens

  • Body and bell: reuse color/icon-button/*.
  • Badge: color/notification-button/badge/background, border, text and dot/background, dot/border. Fill is brand/primary/500 in both modes; border is surface/page.
  • Density: density/notification-button/dot-size 8 · badge-min-height 16 · badge-padding-x 6.

Badge layout

  • Absolutely positioned on the 32px body: dot top 0 / right 0; count top −2 / right 0.
  • 2px outside page-coloured stroke, so the badge never shifts layout.
  • Count text is Poppins Regular 12/16 (caption/sm).

State behavior

  • Focus Visible: Same 2px gap + 2px ring as Icon Button. The badge stays anchored to the body.
  • Disabled: Native disabled. Bell uses content/disabled; badge is unchanged; no opacity (per the Figma variant). Exempt / Disabled state.

Accessibility

  • Count is conveyed in the aria-label (“Notifications, 3 unread” · “Notifications, 99 plus unread”).
  • Badge markup is aria-hidden.

Card

Public

Flexible container for grouped content and actions. 340 wide, radius 12, 1px border, padding 0 on the root; content area padding 24, gap 16. Title heading/sm (Lora SemiBold 20/28), body body/md (Poppins Regular 16/24), footer holds a Small Text Button.

Variants & states

  • Media: None · Image (160px flush media) · Icon (48px container inside the content)
  • Status: Default (elevation/Surface) · Hover (elevation/Raised)
  • Booleans: Show title · Show body · Show footer — hidden sections collapse
Interactive preview

Card title

Use this card to group related content and actions.

Card title

Use this card to group related content and actions.

Card title

Use this card to group related content and actions.

Card title

Use this card to group related content and actions.

Card title

Tokens

  • Color: color/card/background, border, title, body → surface/card, border/default, text/default, text/subtle.
  • Density: density/card/padding 24 · gap 16. Radius 12. Border border/width/sm.
  • Media: image placeholder surface/subtle; icon container action/primary/subtle with a text/subtle glyph.
  • Elevation: Default elevation/Surface, hover elevation/Raised. Same values in Dark (Figma defines no dark alternative).

Layout

  • The image bleeds flush to the top, left, and right and is clipped by the card radius. The icon sits inside the padded content.
  • Hidden title, body, or footer are omitted so no empty gap remains.

Accessibility

  • The card is not clickable as a whole. The action is the real <button> in the footer (keyboard focus shows the Text Button’s 2px stroke).
  • Placeholder media and the decorative icon are aria-hidden.
  • Use a real <img alt="…"> inside .fk-card__media for meaningful images, or alt="" when decorative.

Text Field

Public

Single-line form input. Medium input 48 / padding 16, Small 40 / padding 12, radius 8, 1px inside stroke. Label Poppins Regular 14/20, value 16/24 (Medium) or 14/20 (Small), helper and error caption/md 12/16. Outer stack gap spacing/4; icon-to-text gap 8.

Variants & states

  • State: Default · Hover (1px border/hover) · Active (2px border/hover + caret + 32px cancel) · Filled · Error (1px border/error, red label, warning icon + message) · Error Active (2px error + cancel) · Disabled (disabled tokens + 60% opacity)
  • Focus Visible: Focus Ring boolean — 2px color/border/focus ring, 2px page-coloured gap, radius 10 — not the same as Active. Use :focus-visible.
  • Size: Small (40) · Medium (48)
  • Booleans: Show label · Required · Helper Text · Helper Icon · Leading / Trailing Icon — hidden rows collapse
Interactive preview — hover, click to edit (Active), Tab in (Focus Ring)
Enter a valid email address.
Enter a valid email address.
We will use this to contact you about your account.
We will use this to contact you about your account.

Do

Keep Active (editing chrome) separate from Focus Visible (keyboard ring). Associate error text in code.

Don’t

Don’t rely on placeholder alone as a label. Don’t treat Active as sufficient keyboard focus indication.

Tokens

  • Color: color/text-field/background/*, border/*, text/*, label/*, helper/*, error/*, icon/*, focus/* — resolved for Light and Dark.
  • Density: Small uses 40px height with 12px horizontal padding; Medium uses 48px height with 16px padding.
  • Radius: 8px.
  • Outer gap: spacing/4.

State behavior

  • Focus Visible: :focus-visible draws one 2px ring (color/text-field/focus/ring = border/focus) outside a 2px page-coloured gap.
  • Active: A separate 2px border/hover edit state. It is not a focus substitute.
  • Error: Uses aria-invalid, a warning icon, and an error message. It should not rely on colour alone.
  • Disabled: Native disabled, disabled tokens, and Figma 60% opacity. Exempt / Disabled state.

Accessibility

  • Visible labels use for and id.
  • The no-label example uses aria-label.
  • Helper and error text use aria-describedby.
  • The required asterisk is visual only (aria-hidden); the input uses the native required attribute.

Search Field

Public

Search-specific input aligned with Text Field’s Active + Focus Ring model. Always shows a search icon. Clear appears when text exists.

Accessibility

  • Provide an accessible name.
  • Label the clear button “Clear search”.

Date Picker

Public

Select one specific calendar date (appointment, due date, birth date, start date, report date). Aligns with Text Field / Search Field / Dropdown form-control behavior. Not for date ranges — use a dedicated Date Range Picker pattern when it is available.

Anatomy

  • Label row — label + optional required indicator
  • Date input trigger — placeholder or selected date + calendar icon
  • Support text — helper or error
  • Calendar popover — separate open-state surface (header, weekdays, day grid, Today / Clear)

States & sizes

  • State: Default · Hover · Active · Filled · Error · Error Active · Disabled
  • Focus Visible: Focus Ring boolean (same model as Text Field)
  • Size: Small (~40px) · Medium (~48px)
  • Properties: Show label · Required · Helper Text · Error Text · Show calendar icon · text props
Interactive preview

Choose a date from the calendar.

Calendar day states

  • Default · Hover · Focus Visible · Selected · Today · Disabled · Outside month
  • Day cells are 36px circles (radius/full). Hover and Selected are circular fills; Today is a 2px circular outline; Focus Visible is a 2px color/calendar/day/focus-ring outline.
  • Selected uses color/calendar/day/background/selected + inverse text (not color alone). Today keeps default text with a distinct border.
  • Demo dates mirror the Figma example: Today = Jul 26 · Disabled = Jul 28 · Unavailable (outside, struck through) = Jun 30.

Calendar navigation

Previous/Next month controls use the internal .Base / Calendar / Nav Button component (calendar-specific; visually inspired by Icon Button but not an Icon Button instance). In product code, give them accessible labels Previous month and Next month.

Do

Use Date Picker when users need to select one specific date. Provide a visible label or accessible name. Keep the calendar popover separate from the closed trigger so layout does not reserve empty popover space.

Don’t

Don’t use this for date ranges. Don’t rely on placeholder or the calendar icon as the only label. Don’t recreate Multi-Select Dropdown or Date Range Picker from older templates.

Tokens

  • Color: color/date-picker/*, color/calendar/*.
  • Elevation: elevation/calendar/default.
  • Density: density/calendar/*.
  • Internal: .Base / Calendar / Day Cell, .Base / Calendar / Nav Button.
  • Supporting: Calendar Popover.

Accessibility

  • A visible label or accessible name is required.
  • Associate error text in product code.
  • Focus Visible must stay unclipped.
  • Keyboard users should open the calendar, move between days, select, and close (Escape).
  • Disabled dates are non-interactive. Exempt / Disabled state for contrast.
  • Announce the selected date to assistive technology.
  • The docs example uses semantic buttons for day cells. The calendar icon is decorative (aria-hidden).

Radio Selector

Public

Mutually exclusive choices when all options should stay visible. Indicator 20×20; gap 12; label 16 / description 14.

Checkbox

Public

Independent on/off selection with optional indeterminate. Indicator 20×20, radius 4.

Toggle / Switch

Public

Binary settings control. Track 44×24; thumb 20. On-track uses primary action color.

Email notifications
Receive updates about account activity.
SMS alerts
Optional mobile notifications.

Jumbo Select Button

Public

Large selectable option card. Selected styling uses success green indicator/border (#2F9E60) in live Figma.

  • States: Default · Hover · Pressed · Focus Visible · Selected · Disabled
  • Sizes: Small · Medium · Large
Select one

Accessibility

  • Use a radio pattern for single-select.
  • Selected must not rely on color alone — the check indicator is present.

Snackbar

Public

Short temporary feedback. Tones: Neutral · Success · Warning · Danger · Info. Padding 12×16, radius 12.

Changes saved.

Not for persistent or critical alerts — use Alert / Banner.

Alert / Banner

Public

Persistent system messages. Meaning via text + icons (not color alone).

Update available

A new version is ready to install.

Tooltip

Public

Short contextual help. Placement Top/Right/Bottom/Left with optional arrow. Keep copy short.

More information about this option.

Accessibility

  • Never put critical information only in a tooltip.

Pagination

Public

Pagination Desktop with Size and optional jumper. Page items are 40×40 circles; prev/next use 32 Icon Buttons.

Interactive preview

Progress Bar

Public

Completion across a known process. Always pair the bar with text such as Step 1 of 5 or 20% complete. Fill uses brand primary #D33F55.

  • value: 0% · 20% · 50% · 75% · 100%
  • size: small · medium · large
Static values
20%20% complete
50%50% complete
75%75% complete
100%100% complete
Interactive control
Step 1 of 5 20% complete

Tokens

  • Color: color/progress-bar/*.
  • Lives on the Navigation page (459:2136) with Pagination.

Not current in Figma

NameStatusNotes
TextareaNot in live fileDo not recreate from old templates
TabsNot in live file—
Tag / ChipNot in live file—
Multi-Select DropdownRemoved / not currentDo not recreate
Date Range PickerNot currentSeparate future pattern — do not create from this Date Picker

Accessibility

Fukurou targets WCAG 2.2 Level AA for token and component contrast. Latest tracked audit: 474 pairs · 0 non-exempt failures · 20 exempt disabled · 8 decorative (2026-07-26).

Contrast

  • Normal text ≥ 4.5:1
  • Large text ≥ 3:1
  • Meaningful icons, UI boundaries, focus indicators ≥ 3:1
  • Disabled / inactive controls: mark as Exempt / Disabled state — do not count as non-exempt failures

Focus visible

Keyboard focus must show a visible offset ring. Form controls that use an Active editing state still need a separate Focus Visible treatment (:focus-visible). Do not clip focus rings with parent overflow: hidden.

Keyboard & semantics

  • Icon-only controls need accessible names.
  • Error messaging must be text (not color alone) and associated programmatically.
  • Progress must expose current/min/max values and a text label.
  • Modals: focus trap, Escape, inert background.

Details: ACCESSIBILITY_AUDIT.md · fix plan: SAFE_WCAG_FIX_PLAN.md. Do not claim a live WCAG pass unless the audit against current tokens passed.

Guidelines

Public vs internal components

KindExamplesGuidance
Public setsButton, Text Field, Progress Bar…Publish for designers/engineers
Internal .BasePagination Item, Dropdown Option, Star icon, Calendar Day Cell / NavKeep unpublished; nest inside public sets
Standalone helpersDropdown Menu, Modal Overlay, Cursor Line, Calendar PopoverSupporting pieces — prefer not to expose as primary library entries

When to use what

  • Button for actions; Text Button for low-emphasis text actions; Jumbo Select for choosing an option.
  • Snackbar for temporary feedback; Alert for persistent notices.
  • Radio when all choices are visible and exclusive; Dropdown when space is limited.
  • Date Picker for a single date; Date Range Picker is not a current component.
  • Progress Bar for known completion; always include text.

Naming conventions

  • Collections: 1. Foundation, 2. Theme, 2. Density, 2. Layout, 3. Component.
  • Component tokens: color/{component}/….
  • Internal components often prefix with .Base.

Removed / not current

  • Multi-Select Dropdown is not a current component.
  • Date Range Picker is not a current component (do not create unless explicitly requested).
  • Textarea, Tabs, and Tag / Chip are not in the live Figma file.

Contribution guidance

  1. Inspect the live Figma file and CURRENT_FIGMA_STATE.md before editing.
  2. Do not undo manual Figma changes unless explicitly asked.
  3. Prefer token alias fixes over hard-coded colors.
  4. Update this docs site when public components or architecture change.
  5. Never recreate forbidden components listed above.

Known documentation gaps

  • Pagination and Progress Bar both live on the single Navigation page (459:2136).
  • tokens.json may lag live color count by one.
  • HTML component examples are Figma-matched interactive previews with Light/Dark theme toggle — still approximate vs Code Connect / production components.
  • Textarea / Tabs / Tag are listed as not current — no Figma source to document further.