Design tokens and accessibility
Status
packages/design-tokens is the source of shared UI primitives. M1 Task 7 implements semantic status colors, minimum touch/control sizes, reduced-motion values, shared accessible actions/notices, and Simple/Standard presentation. The M1 review pass (2026-09-19) replaced the muted green palette with the playful direction described below. This document remains the contract for future components and does not claim production accessibility certification.
Visual direction: playful, warm, adult-facing
PlatePilot looks friendly on purpose: a cream background, a bold red primary (#DA291C) with a golden yellow accent (#FFC72C) and deep brown text (#27251F), a green secondary for water and confirmations, bright accent fills for meal slots, large rounded cards (28 px radius), pill-shaped controls, and decorative emoji glyphs. Destructive actions use a darker red so they never read as the primary call to action. The intent is to make everyday logging feel light rather than clinical. The audience is still adults aged 18 and older, so the copy, gating, and disclaimers do not change; only the presentation does.
Rules that keep the playful style accessible and adult-facing:
- Every accent pair (
platePilotAccents) and status tone (platePilotStatusTones) is fixed as a background/foreground couple with at least 4.5:1 text contrast in both color modes. The mobile accessibility test asserts this.
- Glyphs are decorative. They are hidden from assistive technology (
Glyph component) and the adjacent text always states the same information.
- Meal-slot accents (lemon, mint, lavender, peach) and the water accent (sky) identify a category, never a judgment. No color means “good” or “bad” food, and the dashboard tiles cycle accents by position only.
- Status is a labeled pill: glyph plus label plus message. Color is reinforcement, not the carrier.
- Playful does not mean childlike: no child characters or mascots, no reward mechanics, no streaks, no confetti for “hitting a goal”, and no age-ambiguous copy. Celebration glyphs appear only on completed actions the adult chose (for example a saved meal).
- The three main destinations (Today, Log, History) are always one tap away through the bottom navigation bar; deeper screens keep an explicit “Back to Log” action so nothing depends on gestures.
Token model
Designs should reference semantic roles, not raw values. Engineering and Figma must use the same reviewed values.
| Category |
Semantic roles |
| Color |
surface, surface-muted, surface-raised, text, text-muted, border, action, action-hover, focus, success, warning, error, info |
| Typography |
display, heading-lg, heading-md, body, body-strong, label, caption, numeric |
| Spacing |
A documented base scale used consistently for inset, stack, inline, and screen gutters |
| Shape |
Small/medium/large radius and fully rounded action roles |
| Elevation |
Flat, raised, overlay; pair elevation with a visible boundary |
| Motion |
Short/medium durations and standard/emphasized easing, with reduced-motion alternatives |
| Size |
Minimum touch target, control height, icon sizes, and readable content widths |
Do not invent values in a one-off screen. If a needed semantic role is missing, propose it in the token package and handoff notes. The implementation package remains the value source of truth.
Component state matrix
Every interactive component handoff must include:
- Default, pressed, focused, selected, and disabled
- Loading, success, warning, and error where relevant
- Light/dark or supported color modes
- Standard and enlarged text
- Narrow and wide phone widths; web behavior if supported
- Offline, pending, provisional, and stale data variants where relevant
Disabled controls need an explanation when the reason is not obvious. Prefer allowing an action and explaining a recoverable error over unexplained disabling.
Accessibility target
Target WCAG 2.2 AA and platform accessibility conventions before beta:
- Text contrast of at least 4.5:1; at least 3:1 for large text.
- Non-text controls, boundaries, and focus indicators at least 3:1 against adjacent colors.
- Minimum 44 by 44 logical-pixel touch targets unless a stricter platform requirement applies.
- Visible keyboard focus; predictable focus order; no keyboard trap on supported web surfaces.
- Correct names, roles, states, headings, field labels, errors, and live-region announcements.
- Support text resizing to at least 200% without lost content or actions.
- Do not rely on color, position, sound, or motion alone.
- Respect reduced motion and avoid unnecessary animation, flashing, or auto-advancing content.
- Place errors next to their field, summarize them when useful, and move focus appropriately.
- Keep primary actions reachable and distinguish destructive actions by label as well as style.
- Provide text alternatives for meaningful imagery. A meal photo’s user-defined description must not be guessed.
- Format numbers, dates, times, amounts, and units according to locale while preserving clear raw values.
Test with screen readers and keyboard/switch-style navigation on each supported platform; automated checks alone are insufficient.
Nutrition-specific presentation
- Label automated values as estimates and show provenance without overwhelming the default view.
- Use tabs, disclosure, or simple/detailed preference to manage density; do not hide whether data is provisional.
- Do not encode “healthy/unhealthy” as green/red.
- Charts require a text summary, labeled axes/units, adequate contrast, and a non-chart alternative.
- Avoid precision the data source cannot support; display uncertainty in plain language.
- Water and meal progress must not imply a universal medical threshold.
- Explain why camera or photo permission is needed before invoking the platform prompt.
- Retention choice must be understandable without opening a legal document.
- Preserve typed form values after recoverable errors.
- Mark required fields in text; keep optional wellness preferences optional.
- Destructive photo/account actions require a specific confirmation and a result state.
- Upload and analysis progress need a cancellable or leave-and-return path where technically possible.
Validation checklist