Capablio

Handbook

Prompt 03 — Design system and application shells

This is the first production implementation prompt. Work in small, reviewable slices and preserve existing routes until replacements are ready.

Updated

Required context

  • Approved target architecture from prompt 02
  • 04-layout-and-design-system-guidelines.md
  • Existing UI framework, component library, styles, and accessibility tooling
  • Screens 01, 02, 07, 08, 09, 14, and 16 as current-state references

Prompt

Build the shared Capablio experience foundation. Do not implement all domain workflows in this prompt.

1. Audit before adding dependencies

Identify the current design primitives, CSS approach, icon set, chart library, form library, table library, and story/example tooling. Reuse or extend them when they meet the requirements. Do not add a second component system or styling framework without an ADR and migration reason.

2. Create semantic design tokens

Implement token groups for:

  • Color: surfaces, text, borders, actions, statuses, brand, focus, chart relationships
  • Typography
  • Spacing
  • Radius
  • Elevation
  • Control heights
  • Layout widths
  • Motion and reduced motion
  • Z-index layers
  • Light and dark themes

Preserve Capablio amber/lime as brand accents. Make light theme the default unless an approved product decision states otherwise. Validate contrast and document token usage.

3. Build or normalize core components

At minimum:

  • Button and icon button
  • Link
  • Text input, textarea, select, combobox, date/period input
  • Checkbox, radio, switch
  • File upload / drop zone
  • Field, help text, error summary
  • Badge/status chip
  • Alert/callout
  • Toast
  • Tooltip
  • Breadcrumb
  • Tabs
  • Pagination
  • Empty state
  • Error state and 403/404/500 pages
  • Skeleton and progress
  • Modal, confirmation dialog, drawer/sheet
  • Card/section surface
  • Page header
  • Filter toolbar
  • Data table shell
  • Stepper
  • Workspace switcher
  • Tenant/scope indicator
  • User menu and notifications trigger
  • Chart frame with accessible table fallback

Every component must document default, hover, focus, active, disabled, loading, error, and dark-theme states where applicable.

4. Build three shells

Marketing shell

Header, mobile navigation, footer, content container, announcement slot, and CTA patterns.

Documentation shell

Search slot, left nav, reading column, right table of contents, version/last-updated metadata, previous/next, and page feedback.

Product shell

Top bar, workspace switcher, tenant/scope context, role-aware side navigation, command/search slot, help, notifications, user menu, responsive drawer, page container, and privileged-session banner.

5. Prove the system on representative pages

Migrate only these representative screens first:

  1. Subject home → a basic Today shell with realistic task cards and empty states
  2. Tenant user directory → data table, filters, detail drawer shell
  3. Access denied → accessible branded 403 page

Use fixtures where backend changes are not yet in scope, but keep fixtures clearly separated from production data paths.

6. Documentation and tests

  • Create component usage documentation/examples in the repository's existing system.
  • Add visual regression where available.
  • Add keyboard and automated accessibility tests for shell navigation, modal/drawer, fields, and table controls.
  • Test mobile, tablet, desktop, 200% zoom, and reduced motion.
  • Update external design/accessibility docs and internal component architecture.

Acceptance gates

  • No page-local hard-coded brand/status colors in migrated pages.
  • All migrated pages render in light and dark themes.
  • Workspace navigation is keyboard operable and shows active tenant/scope.
  • Mobile navigation does not trap or lose focus.
  • The user table has meaningful loading, empty, filtered-empty, error, and permission states.
  • No raw browser file/input styling remains in the new component library.
  • Existing unaffected routes continue to work.