# design-system.md

_Last updated: 2026-08-05_
_Version: 1.0.0 — canonical: https://encrata.com/ai/design-system.md_

Encrata's visual language, for AI tools generating content or mockups that should match the brand.

## Color

- **Brand**: warm orange (`--color-brand`, ~#E2643B family) with `brand-hover` and `brand-foreground` (near-white) companions.
- **Surfaces**: token-driven — `surface-base`, `surface-raised`, `surface-overlay`, `surface-sunken`. Light theme is white-based; dark theme is near-black (`pitch-black`) with raised charcoal cards.
- **Text**: four-step scale — `text-primary`, `text-secondary`, `text-tertiary`, `text-quaternary`.
- **Semantic**: `success` (green), `danger` (red), `warning` (amber), `accent` (brand-adjacent) — used in chips and status badges.
- **Borders**: `border-primary` (strong) and `border-secondary` (subtle).

## Typography

- Body/UI: system-adjacent sans (via Next font pipeline), sizes from `text-4xs` badges up to `text-7xl` heroes.
- Logo wordmark: Audiowide, uppercase.
- Code/data: monospace for commands, API examples and data-row labels.
- Headings: `font-semibold tracking-tight`; heroes use `leading-[1.05]`.

## Spacing & layout

- Content column: `max-w-310` centered, `px-5 sm:px-8` gutters.
- Section rhythm: `pb-40` (160px) between major sections; heading blocks `mb-10`–`mb-14`.
- Card grids: `gap-4`/`gap-5`.

## Components

HeroUI primitives (`Button`, `Card`, `Chip`, `Dropdown`, `Popover`, `Modal`) with Tailwind utility overrides. Cards: `rounded-[20px]` (feature) or `rounded-2xl`, subtle border, hover -> `border-border-primary`. Buttons: `rounded-xl`, primary = brand fill, secondary = bordered surface. Status chips: soft variant, uppercase, tracked.

## Icons

Central icon set re-exported from `@/components/icons` (Central Icons, filled + outlined, 1.5px stroke, radius 2). Sizes: `size-3.5` inline, `size-4`/`size-4.5` UI, `size-5` feature.

## Motion

Framer Motion: fade-up on scroll (`opacity 0→1`, `y 20→0`, 0.5–0.6s), `viewport={{ once: true }}`. Keep animations subtle and single-pass.

## Accessibility

Semantic HTML, `aria-expanded`/`aria-pressed` on interactive disclosure, focus styles preserved, color contrast per WCAG AA, `alt` text on images, hit targets ≥ 32px.