Design System Reference

Repository: equa-patternlib-nextjs | Storybook: http://localhost:6006 | Next.js dev: http://localhost:3001

Overview

Equa’s design system is maintained in the equa-patternlib-nextjs repository and consumed by equa-web via the equa-patternlib package (installed from GitHub). Source: equa-web/package.json (dependency: equa-patternlib from github:EQUAStart/equa-patternlib-nextjs#master)

Component Inventory

Source: equa-patternlib-nextjs/stories/ (45 story files verified)

Component	Story File	Purpose
EquaAvatar	`EquaAvatar.stories.tsx`	User/org profile images with fallback initials
EquaBadge	`EquaBadge.stories.tsx`	Status indicators and labels
EquaButton	`EquaButton.stories.tsx`	Primary, secondary, ghost, danger actions
EquaCard	`EquaCard.stories.tsx`	Content containers with header/body/footer
EquaCheckbox	`EquaCheckbox.stories.tsx`	Boolean input with label
EquaChip	`EquaChip.stories.tsx`	Tag-style compact labels
EquaDatePicker	`EquaDatePicker.stories.tsx`	Date selection with calendar dropdown
EquaDropdown	`EquaDropdown.stories.tsx`	Select menus and option lists
EquaFileUpload	`EquaFileUpload.stories.tsx`	Drag-and-drop file upload zone
EquaInput	`EquaInput.stories.tsx`	Text, email, password, number inputs
EquaMenu	`EquaMenu.stories.tsx`	Navigation and context menus
EquaModal	`EquaModal.stories.tsx`	Dialog overlays for forms and confirmations
EquaPagination	`EquaPagination.stories.tsx`	Page navigation controls
EquaProgress	`EquaProgress.stories.tsx`	Progress bars and loading indicators
EquaRadio	`EquaRadio.stories.tsx`	Radio button groups
EquaRating	`EquaRating.stories.tsx`	Star rating display/input
EquaSidebar	`EquaSidebar.stories.tsx`	Navigation sidebar layout
EquaSkeleton	`EquaSkeleton.stories.tsx`	Loading placeholder shapes
EquaSlider	`EquaSlider.stories.tsx`	Range slider input
EquaStepper	`EquaStepper.stories.tsx`	Multi-step progress indicator
EquaSwitch	`EquaSwitch.stories.tsx`	Toggle switch input
EquaTable	`EquaTable.stories.tsx`	Data tables with sorting and pagination
EquaTabs	`EquaTabs.stories.tsx`	Tab navigation
EquaToast	`EquaToast.stories.tsx`	Notification toasts
EquaToggle	`EquaToggle.stories.tsx`	On/off toggle
EquaTooltip	`EquaTooltip.stories.tsx`	Hover tooltips

Token Architecture (Cross-Framework)

The Equa design system uses a JSON-first token pipeline that feeds both React (Storybook + equa-web) and Lit (gateway dashboard) systems.

Source of Truth

design-tokens.json (W3C format)
       │
       ├──→ design-tokens.css   (CSS custom properties — consumed by gateway Lit + Storybook)
       ├──→ tokens/index.ts     (typed JS exports — available for React imports)
       └──→ generated-theme-values.ts  (JS constants — consumed by theme.ts)

Build command: npm run tokens in equa-patternlib-nextjs CI check: npm run tokens:check — exits 1 if generated files are stale

Gateway Consumption (Lit + CSS Custom Properties)

The gateway loads design-tokens.css via styles.css:1, then base.css aliases short names to canonical tokens:

/* base.css — alias layer */
:root {
  --bg: var(--color-ui-background);
  --card: var(--color-ui-surface);
  --accent: var(--color-brand-primary);
  /* ~67 aliases total */
}

Gateway component CSS uses the short names (var(--bg), var(--card)), which resolve through the alias chain to canonical token values. This means gateway CSS files never need to change when token values are updated.

Patternlib Consumption (React + styled-components)

The patternlib’s theme.ts imports from generated-theme-values.ts:

import { RADIUS_SM, SHADOW_SM, COLOR_UI_BACKGROUND } from './generated-theme-values';

export const equaTheme: Theme = {
  radius: RADIUS_SM,       // '6px'
  boxShadow: SHADOW_SM,    // '0 1px 2px rgba(0, 0, 0, 0.2)'
  header: COLOR_UI_BACKGROUND,
  // ...
};

Components access tokens via props.theme.xxx in styled-components. Values stay in sync because generated-theme-values.ts is produced from the same design-tokens.json.

Modifying Tokens

Edit equa-patternlib-nextjs/src/tokens/design-tokens.json
Run npm run tokens to regenerate CSS, TS, and theme values
Copy updated design-tokens.css + design-tokens.json to equabot-gateway/ui/src/tokens/
Copy updated theme.ts + generated-theme-values.ts to equa-web/src/styles/
Verify: npm run tokens:check exits 0, npm run test passes in both repos

Design Tokens

Source: equa-patternlib-nextjs/stories/DesignTokens.mdx

Color Palette

Token Category	Purpose
Brand	Primary green (`#33AA40`), secondary, accent
Background	Surface (`#263946`), card, elevated, overlay
Neutral	Text (`#e4e4e7`), borders (`#435763`), dividers, disabled states
Semantic	Success (green), warning (amber), error (red), info (blue)

Typography

Token	Value
`--font-family-base`	Nunito Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif
`--font-family-mono`	JetBrains Mono, ui-monospace, SFMono-Regular, SF Mono, Menlo, Monaco, Consolas, monospace
Font sizes	`--font-size-xxs` (12px) through `--font-size-xxxl` (48px)

Font loading: All @font-face declarations in equa-web/src/styles/global.ts include font-display: swap to prevent Flash of Invisible Text (FOIT). The 6 NunitoSans variants (Regular, SemiBold, Black, Bold, ExtraBold, Light) load progressively; text renders immediately with the system fallback font and swaps to NunitoSans when available. New @font-face rules must always include font-display: swap.

Spacing

Scale from --spacing-xxs (4px) to --spacing-xxxl (50px), used for padding, margins, and gaps.

Border Radius

Token	Value	Usage
`--radius-sm`	6px	Small elements (chips, badges)
`--radius-md`	8px	Default (buttons, inputs, cards)
`--radius-lg`	12px	Larger containers (modals)
`--radius-xl`	16px	Extra-large containers
`--radius-full`	9999px	Pills and circles

Shadows

Base shadows use rgba(0, 0, 0, 0.2) opacity. Gateway extends with --shadow-glow and --card-highlight for dark-mode depth effects.

Themes

Theme	Systems	Description
Equa (Dark)	Gateway, Storybook, equa-web	Default dark teal/navy palette with green accent
Light	Gateway, Storybook, equa-web	White/gray palette with green accent
Midnight	Storybook, equa-web only	Darker navy palette (not in gateway)

The token system provides dark and light themes. Midnight is an equa-web consumer feature, not needed in the gateway admin tool. Theme switching in equa-web: ThemeProvider in equa-web/src/app/app.tsx, persisted via cookies. Theme switching in gateway: [data-theme="light"] CSS override block, with system preference detection.

Integration Pattern

In equa-web

Components are re-exported via equa-web/src/shared/components/ for local aliasing:

import { EquaButton } from '@components/EquaButton';

The webpack alias @components maps to src/shared/components/.

In Storybook

cd ~/Documents/repos/equa-patternlib-nextjs
npm run storybook
# Opens at http://localhost:6006

Storybook Configuration

Source: equa-patternlib-nextjs/stories/Configure.mdx Covers: styling setup, context providers, asset loading, and addon configuration.

Gateway-Aligned Components

In addition to the core patternlib components, 10 gateway-aligned components bridge the gateway Lit UI and the React Storybook:

Component	Story	Gateway CSS Match	Status
ChatBubble	EquaChatBubble	`.chat-bubble`, `.chat-line`	Shared
CodeBlock	EquaCodeBlock	`.code-block`	Shared
LogEntry	EquaLogEntry	`.log-row`, `.log-level`	Shared
KeyValueRow	EquaKeyValueRow	`.config-diff__item`	Shared
FormLayout	EquaFormLayout	`.field`, `.cfg-input`, `.cfg-toggle`	Shared
ConfigSection	EquaConfigSection	`.config-section-card`, `.config-section-hero`	Shared
ToolCard	EquaToolCard	`.chat-tool-card`	Shared
ChatCompose	EquaChatCompose	`.chat-compose`	Shared
ExecApproval	EquaExecApproval	`.exec-approval-card`, `.exec-approval-overlay`	Shared
ConfigSearch	EquaConfigSearch	`.config-search`	Shared

Gateway-Internal Patterns (Not in Storybook)

These 4 patterns remain gateway-only due to low cross-product reuse:

Pattern	Gateway CSS	Rationale
Chat Split Container	`.chat-split-container`	Tightly coupled to Lit resize observer
Config Diff	`.config-diff`	Specific to gateway config key/value changes
Compaction Indicator	`.compaction-indicator`	Single-use AI context compaction animation
QR Code Display	`.qr-wrap`	Trivial dashed-border wrapper

Adding New Components

Create the component in equa-patternlib-nextjs/src/components/
Create a story file in stories/EquaComponentName.stories.tsx
Export from the package index
Install updated package in equa-web via yarn upgrade equa-patternlib
Re-export in equa-web/src/shared/components/ if using the alias pattern

Platform Architecture

Compliance & Security

Feature Specifications

Developer Onboarding

Business

Reference & Templates

Design System Reference

Design System Reference

Overview

Component Inventory

Token Architecture (Cross-Framework)

Source of Truth

Gateway Consumption (Lit + CSS Custom Properties)

Patternlib Consumption (React + styled-components)

Modifying Tokens

Design Tokens

Color Palette

Typography

Spacing

Border Radius

Shadows

Themes

Integration Pattern

In equa-web

In Storybook

Storybook Configuration

Gateway-Aligned Components

Gateway-Internal Patterns (Not in Storybook)

Adding New Components

Platform Architecture

Compliance & Security

Feature Specifications

Developer Onboarding

Business

Reference & Templates

​Design System Reference

​Overview

​Component Inventory

​Token Architecture (Cross-Framework)

​Source of Truth

​Gateway Consumption (Lit + CSS Custom Properties)

​Patternlib Consumption (React + styled-components)

​Modifying Tokens

​Design Tokens

​Color Palette

​Typography

​Spacing

​Border Radius

​Shadows

​Themes

​Integration Pattern

​In equa-web

​In Storybook

​Storybook Configuration

​Gateway-Aligned Components

​Gateway-Internal Patterns (Not in Storybook)

​Adding New Components

Design System Reference

Overview

Component Inventory

Token Architecture (Cross-Framework)

Source of Truth

Gateway Consumption (Lit + CSS Custom Properties)

Patternlib Consumption (React + styled-components)

Modifying Tokens

Design Tokens

Color Palette

Typography

Spacing

Border Radius

Shadows

Themes

Integration Pattern

In equa-web

In Storybook

Storybook Configuration

Gateway-Aligned Components

Gateway-Internal Patterns (Not in Storybook)

Adding New Components