> ## Documentation Index > Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # DESIGN # Ara design Version: 1.3.3. Last verified: 2026-08-25. This is the repository-wide contract for rendered and user-facing design. Ara uses one visual language across the product app, marketing pages, public docs, emails, templates, and preview routes. A route or component may specialize the system, but it may not create a competing one. HARD RULE: Before changing any rendered or user-facing surface, read this file. Update this file in the same change when a durable design rule changes. HARD RULE: Verified implementation is execution truth. When this document and the current components, tokens, or rendered behavior disagree, fix the mismatch promptly. Do not preserve a known false design instruction for later cleanup. ## Source map Use these owners instead of copying values into a route: | Concern | Source of truth | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | Global app tokens, themes, and shared app styles | [`frontend/src/styles.css`](frontend/src/styles.css) | | Reusable component styles | [`frontend/src/styles/design-system.css`](frontend/src/styles/design-system.css) | | Reusable React primitives | [`frontend/src/components/ui/`](frontend/src/components/ui/) and its [`index.ts`](frontend/src/components/ui/index.ts) | | Motion curves, durations, and springs | [`frontend/src/lib/motion.ts`](frontend/src/lib/motion.ts) | | Product icon facade | [`frontend/src/lib/hugeicons.tsx`](frontend/src/lib/hugeicons.tsx) | | Brand and home-screen icons | [`frontend/public/ara-logo/`](frontend/public/ara-logo/) and [`scripts/make-favicon.py`](scripts/make-favicon.py) | | Marketing surfaces | [`frontend/src/pages/marketing/`](frontend/src/pages/marketing/) | | Public documentation shell | [`docs.json`](docs.json) and [`docs/public/`](docs/public/) | The source owns exact token values. This file owns the durable choices and selection rules. Do not duplicate a palette here and let it drift from CSS. ## References * Product app: Codex and the ChatGPT macOS app for low chrome, soft contrast, restrained elevation, and native-feeling panels. * Marketing: Cursor for editorial type scale, clean layout, restrained spacing, and legibility. * Typography: system UI for interface and prose; `var(--ara-mono-font)` for code, tokens, identifiers, versions, and timestamps. ## Visual language * Prefer low chrome, soft contrast borders, restrained elevation, and native-feeling panels. Hierarchy should come from spacing, type, and surface contrast before decoration. * Use semantic tokens such as `--chrome`, `--panel`, `--ink`, `--muted`, `--line`, `--accent`, and `--brand`. Never hard-code a theme color in a new component when a semantic token expresses the role. * Support both `data-theme="light"` and `data-theme="dark"`. A value that works in one theme is not finished. * Keep marketing layouts editorial and left-aligned. Centered announcement banners are the narrow exception. * Descriptions and card bodies are readable prose, not microcopy. Use the established 15-18px body scale unless the text is genuinely metadata. * Keep flowing prose and typed text from breaking mid-word. ### Typography hierarchy Use this role scale across marketing, documentation, changelog, articles, and app surfaces. A specialized view may use a tighter established component scale, but it must preserve the same hierarchy. | Role | Size | Weight | Line height | Tracking | | ----------------------- | -------------------------- | --------- | ----------- | ------------- | | Homepage hero title | `clamp(42px, 5vw, 68px)` | `400` | `0.95` | `-0.065em` | | Homepage hero lede | `clamp(18px, 2.2vw, 22px)` | `400` | `1.45` | `-0.02em` | | Page display title | `clamp(32px, 4vw, 42px)` | `400` | `1.15` | `-0.035em` | | Section heading | `clamp(24px, 2.8vw, 32px)` | `400-500` | `1.15` | `-0.04em` | | Section lede | `16-18px` | `400` | `1.5` | `-0.015em` | | Card heading | `16-24px` | `500` | `1.25-1.35` | `-0.02em` | | Card or article body | `15-16px` | `400` | `1.55-1.6` | normal | | Navigation and actions | `14-15px` | `400-600` | `1.4` | normal | | Metadata and timestamps | `12-13px` | `400` | `1.5` | `0.02em` | | Eyebrow or overline | `11-13px` | `600` | `1` | `0.08-0.12em` | ## Component choices Start with the primitives exported from `frontend/src/components/ui`. Extend an existing primitive when the interaction contract is shared; keep a specialized component local when its behavior belongs to one product domain. * `Button`, `IconButton`, inputs, `Checkbox`, `Switch`, and `FormField` own ordinary controls and their focus, disabled, loading, and error states. * `SegmentedControl` switches between a small set of compact peer values. * `Tabs` switches between peer views. Use `MorphingTabs` only when the moving surface and transition are central to a large, self-contained experience. * `Select` chooses one value. `CascadingSelect` is for a real hierarchy, not a decorative menu. * `AnchoredMenu` and `MenuSurface` contain commands. `PopoverSurface` contains interactive contextual content. Tooltips stay short and passive. * `Drawer` owns side detail; `MorphingModal` owns a bounded modal task. * `Accordion` owns expandable supporting information, not primary navigation. Do not invent a one-off card, button, menu, tab, tooltip, or modal system when the shared layer already owns the interaction. Session chat and new conversation share one page-level wait: the empty-canvas composer dock in `WorkspaceChatSkeleton`. Do not add a second chat-entry skeleton family (fake greeting, dual picker, transcript mock, or wordmark) once the route is a workspace chat surface. Settings, billing, codebases, and customize keep their existing card or row skeletons. Authored Mintlify MDX uses `` and `` for ordinary documentation cards. Reserve `.ara-template-card` for large illustrated template cards. ## Icons HARD RULE: Central Icons is the only product icon library. Import existing names through `frontend/src/lib/hugeicons.tsx` or import a missing Central glyph directly. Do not introduce, select, or use an icon from another library for a product surface. Never hand-author an inline SVG. Directional pointed symbols may use the established Tabler exception. Browser tab favicons (`rel=icon`, `favicon.ico`, 16, 32, and any 512 used as a tab icon) use an opaque rounded plate on a transparent canvas with a slightly inset mark. Apple-touch (180) and dedicated PWA maskable 192/512 stay opaque full-bleed squares — iOS applies its own home-screen mask. `staging.ara.so` uses the white-on-black family (black plate); `ara.so` uses black-on-white (white plate). Host selection lives in `middleware.ts`, not in per-environment binaries. ## Motion Use the tokens in `frontend/src/lib/motion.ts`; do not inline new cubic-bezier or spring values in a component. Motion should explain state, continuity, or spatial origin. It must not delay input, hide progress, or animate streaming tokens. Honor `prefers-reduced-motion` with an immediate, fully usable state. ## Responsive and accessible behavior * Design and verify representative desktop and mobile widths. * Phone pull-request review is one stacked page (summary, discussion, files, diff) with a single floating glass Back. Do not add Overview / Discussion / Commits pills or a second header icon row on `max-width: 780px`. Keep diffs smaller than the surrounding chrome so line gutters cannot eat the viewport. * Preserve logical reading order when grids or split cards stack. * Every interactive control needs a visible focus state, an accessible name, keyboard behavior, and a sufficient target size. * Do not communicate state by color alone. Error, success, selected, loading, and disabled states need a second signal. * Route changes reset scroll to the top unless the route intentionally restores position or follows an explicit hash anchor. ## Change workflow 1. Find the owning route and the nearest shared primitive, token, and precedent. 2. State the interaction and responsive contract before styling it. 3. Implement the smallest coherent change using the owners above. 4. Expose work-in-progress UI at `/preview/{component}`. Label alternatives visibly as `Option 1`, `Option 2`, and so on. 5. Verify the real route in light and dark themes, at desktop and mobile widths, with keyboard focus and reduced motion where relevant. 6. Retain before-and-after evidence for a rendered change and follow the delivery path in [`DEVELOPMENT.md`](DEVELOPMENT.md). ## Living contract Change this file only from verified source or rendered evidence. Replace the smallest stale rule, delete the superseded instruction, re-run the affected visual proof, bump the version, and add one changelog line. Keep the latest ten entries; Git retains older history. ## Changelog * v1.3.3 (2026-08-25): Restored the rounded, inset tab-favicon plate; apple-touch and dedicated PWA maskable assets stay full-bleed. * v1.3.2 (2026-08-25): Phone pull-request review keeps one floating glass Back and a stacked all-in-1 page; diffs stay smaller than the chrome. * v1.3.1 (2026-08-25): Session chat and new conversation share one empty-canvas composer-dock wait; settings and list waits stay separate. * v1.3.0 (2026-08-25): Required full-bleed home-screen icons and a host-selected staging (white-on-black) vs prod (black-on-white) colorway. * v1.2.1 (2026-08-24): Made Central Icons the exclusive product icon library. * v1.2.0 (2026-08-23): Added the Mintlify card ownership rule. * v1.1.0 (2026-08-23): Made DESIGN the required repository-wide UI contract, replaced drifting copied tokens with source owners, and added component, icon, motion, responsive, accessibility, and verification rules. * v1.0.0 (2026-08-23): Added the initial typography, theme, layout, and design references.