From a46777619a1183bf11d434c3fbadbd9a11db5318 Mon Sep 17 00:00:00 2001 From: francy51 Date: Fri, 13 Mar 2026 15:00:17 -0400 Subject: [PATCH] Add design system documentation --- docs/DESIGN_SYSTEM.md | 391 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 docs/DESIGN_SYSTEM.md diff --git a/docs/DESIGN_SYSTEM.md b/docs/DESIGN_SYSTEM.md new file mode 100644 index 0000000..83b2556 --- /dev/null +++ b/docs/DESIGN_SYSTEM.md @@ -0,0 +1,391 @@ +# Fiscal Clone Design System + +This file is the shared design reference for Fiscal Clone. Use it when building new components, revising existing screens, or making frontend design decisions. + +## How to use this document + +- Treat this file as the human-readable source of truth for UI decisions. +- Treat `app/globals.css` as the implementation source of truth for tokens already in code. +- If a new UI pattern is introduced, update this document in the same change so the system does not drift. +- Prefer extending an existing pattern before inventing a new one. + +## Product and visual intent + +Fiscal Clone is a financial analysis terminal, not a generic SaaS dashboard. + +The UI should feel: + +- focused +- technical +- data-dense without looking cramped +- calm and high-confidence +- operational, with clear state and hierarchy + +The current visual language is a dark research workstation with muted chrome, soft glass-like surfaces, monospaced metadata, and restrained highlights. + +## Core design principles + +1. Data first. Numbers, charts, and evidence should dominate decorative elements. +2. Restraint over novelty. Avoid bright accents, oversized illustrations, and consumer-app styling. +3. One primary action per area. Panels and toolbars should make the next step obvious. +4. Reuse familiar surfaces. Panels, pills, tables, and toolbars should feel like parts of one terminal. +5. Dense, not crowded. Compact layouts are fine, but preserve scanability and whitespace between blocks. +6. Status must be legible. State should never depend on color alone. +7. Motion is ambient, not performative. Animation should support orientation, not demand attention. + +## Brand voice and tone + +Interface copy should sound like an analyst workstation: + +- concise +- factual +- operational +- low-hype + +Prefer: + +- "Load overview" +- "Queue AI insight" +- "Recent tasks" +- "Runtime state: stable" + +Avoid: + +- playful marketing language +- vague CTA labels like "Explore" or "Learn more" +- overly conversational empty states + +## Layout system + +### Application shell + +The app shell is the primary frame for authenticated product surfaces. + +- Left navigation is the persistent desktop anchor. +- Mobile navigation is task-oriented and bottom-docked. +- Every page should have a clear title, optional subtitle, and optional action group. +- Breadcrumbs should orient the user inside research workflows, especially when a ticker is active. + +Reference implementation: `components/shell/app-shell.tsx` + +### Page structure + +Use this ordering for most product pages: + +1. page title and subtitle +2. top-level actions +3. summary metrics or controls +4. primary content panels +5. secondary detail or supporting panels + +### Grid guidance + +- Prefer `gap-2` for tight dashboard summaries. +- Prefer `gap-4` for full content sections. +- Use one-column layout by default on mobile. +- Expand to two or three columns only when comparison improves comprehension. +- Keep important analytical content in the left or center visual path. + +### Width and spacing + +- The Tailwind container is centered with `2rem` horizontal padding and a `1400px` `2xl` width. +- Major surfaces typically use `rounded-2xl`. +- Controls typically use `rounded-xl`. +- Default panel padding is `p-4` on mobile and `sm:p-5` or `sm:p-6` on larger screens. + +## Typography + +### Font roles + +- Primary UI font: `--font-display` +- Monospaced metadata font: `--font-mono` + +The display font is used for headings, paragraph content, and core UI. The mono font is reserved for labels, captions, table headers, status metadata, and technical framing. + +Reference implementation: `app/globals.css` + +### Type hierarchy + +- Page titles: `text-2xl` to `text-3xl`, semibold +- Section titles: `text-lg` to `text-xl`, semibold +- Panel titles: `text-base` +- Body copy: `text-sm` with generous line height where content is dense +- Metadata and eyebrow labels: `text-xs` or `text-[11px]`, uppercase, increased letter spacing + +### Typography rules + +- Use uppercase mono labels for section identifiers, table headers, and compact metadata. +- Avoid long all-caps paragraphs. +- Keep body copy left-aligned. +- Keep line length moderate for explanatory text. + +## Color and surface system + +### Primary tokens + +These tokens already define the current visual system: + +| Token | Value | Usage | +| --- | --- | --- | +| `--bg-0` | `#121417` | page background base | +| `--bg-1` | `#181b20` | page background mid | +| `--bg-2` | `#21252b` | page background depth | +| `--panel` | `rgba(28, 31, 36, 0.84)` | primary panel surface | +| `--panel-soft` | `rgba(36, 39, 45, 0.72)` | secondary panel or hover surface | +| `--panel-bright` | `rgba(49, 53, 60, 0.94)` | stronger elevated surface | +| `--line-weak` | `rgba(196, 202, 211, 0.18)` | default border | +| `--line-strong` | `rgba(220, 226, 234, 0.34)` | active or hover border | +| `--accent` | `#d9dee5` | restrained accent | +| `--accent-strong` | `#f4f7fb` | brighter accent state | +| `--danger` | `#ff8e8e` | destructive state | +| `--danger-soft` | `rgba(111, 46, 46, 0.42)` | destructive surface | +| `--terminal-bright` | `#f3f5f7` | primary foreground | +| `--terminal-muted` | `#a1a9b3` | secondary foreground | +| `--focus-ring` | `rgba(229, 231, 235, 0.14)` | focus halo | + +Reference implementation: `app/globals.css` + +### Color usage rules + +- Use muted neutrals for most surfaces and borders. +- Use `--accent` sparingly for links, primary actions, and selected emphasis. +- Use `--danger` only for destructive actions or failure states. +- Success color may appear in metrics, but should remain understated. +- Never rely on saturated color blocks as the main visual identity. + +### Background treatment + +Backgrounds should feel atmospheric and infrastructural: + +- layered radial gradients +- subtle grid textures +- low-opacity noise + +These effects support the terminal identity and should remain secondary to content. + +## Shape, borders, and depth + +- Standard control radius: `rounded-xl` +- Standard panel radius: `rounded-2xl` +- Most surfaces use a 1px border with `--line-weak` +- Hover and active states strengthen the border before changing fill aggressively +- Shadows should feel soft and deep, not crisp or card-like + +## Component decisions + +### Buttons + +There are four established button variants: + +- `primary` +- `secondary` +- `ghost` +- `danger` + +Button rules: + +- Minimum touch height is `44px` via `min-h-11` +- Use icon-plus-label pairs when the action benefits from faster scanning +- Keep labels direct and verb-based +- Prefer `primary` for the single most important action in a local group +- Use `secondary` for adjacent supporting actions +- Use `ghost` for low-emphasis actions +- Use `danger` only when the action is irreversible or risky + +Reference implementation: `components/ui/button.tsx` + +### Inputs + +Inputs use soft panel surfaces with a stronger border and subtle halo on focus. + +Input rules: + +- Minimum touch height is `44px` +- Placeholder text should remain muted and never act as the only label +- External labels are preferred for forms +- Search and symbol-entry fields may include leading icons + +Reference implementation: `components/ui/input.tsx` + +### Panels + +Panels are the core information container. + +Use `surface` panels for: + +- grouped data blocks +- modal-like sections +- elevated analytical modules + +Use `flat` sections for: + +- page subsections +- inline grouped content that does not need a full card treatment + +Panel rules: + +- Titles should be short and descriptive +- Subtitles should explain context or time horizon +- Header actions should stay compact +- Avoid stacking too many fully elevated panels when a flatter rhythm improves readability + +Reference implementation: `components/ui/panel.tsx` + +### Status pills and tags + +Status pills should be compact, uppercase, and visually coded, but the text label must remain meaningful on its own. + +Use pills for: + +- job status +- research posture +- small categorical states + +Reference implementation: `components/ui/status-pill.tsx` + +### Metric cards + +Metric cards are terse summary blocks, not mini-panels. + +Rules: + +- lead with the metric value +- keep the label in mono uppercase style +- use delta text only for meaningful comparison or trend context +- reserve green and red text for clearly directional values + +Reference implementation: `components/dashboard/metric-card.tsx` + +### Tables + +Tables are a first-class pattern in this product. + +Rules: + +- use `.data-table` and `.data-table-wrap` styles where possible +- table headers should use mono uppercase metadata styling +- row hover may add a subtle background, but should not reduce readability +- numeric columns should remain easy to compare visually +- avoid decorative striping unless it materially helps scanability + +Reference implementation: `app/globals.css` + +### Navigation links + +Navigation and quick links should feel like terminal controls, not marketing cards. + +Rules: + +- prefer border, text, and surface changes over large movement +- active states should be obvious from both color and structure +- keep mobile nav labels short + +## Interaction and motion + +### Interaction rules + +- Hover states should generally strengthen border, foreground, or surface contrast. +- Focus states must always be visible. +- Loading states should be plain and informative. +- Empty states should explain what to do next. +- Error states should be specific and concise. + +### Motion rules + +- Standard transition duration is about `200ms` +- Keep motion subtle and utility-driven +- Ambient background animation is acceptable when low contrast and slow +- Respect `prefers-reduced-motion` +- Do not add decorative animation to dense analytical surfaces + +Reference implementation: `app/globals.css` + +## Responsive behavior + +- Mobile should preserve the same visual language, not switch to a different product identity. +- Collapse complex layouts vertically before removing information. +- Horizontal scroll is acceptable for dense tables, but not for primary page structure. +- Mobile action groups should stack cleanly and remain thumb-friendly. +- Reduce background intensity slightly on small screens to preserve legibility. + +References: + +- `components/shell/app-shell.tsx` +- `components/auth/auth-shell.tsx` +- `app/globals.css` + +## Accessibility baseline + +All new UI should meet this baseline: + +- WCAG 2.1 AA contrast for body text and controls +- keyboard access for all interactive elements +- visible focus styles +- labels for all inputs +- no color-only status communication +- readable hit targets at or above 44x44px where practical +- motion should degrade gracefully for reduced-motion users + +Additional guidance: + +- Use semantic HTML first. +- Use ARIA only when native semantics are insufficient. +- Keep tab order aligned with the visual reading order. +- Preserve text clarity over background effects. + +## Page-specific patterns + +### Auth pages + +Auth pages use a split layout: + +- one side for product framing +- one side for the form + +This area should feel slightly more cinematic than the internal app, but still restrained and operational. + +Reference implementation: `components/auth/auth-shell.tsx` + +### Research and analysis pages + +These pages are company-first and should foreground the selected ticker, current context, and next analytical move. + +Use: + +- a strong top toolbar +- fast context switching between adjacent research surfaces +- supporting metadata close to the relevant content + +Reference implementation: `components/analysis/analysis-toolbar.tsx` + +## Rules for adding new components + +Before adding a new component: + +1. Check whether `Button`, `Input`, `Panel`, table styles, pills, or existing shell patterns already solve the need. +2. Reuse existing tokens before introducing new colors, radii, shadows, or spacing values. +3. Match the established terminal tone in both visuals and copy. +4. Test the component in mobile and desktop layouts. +5. Verify keyboard focus, contrast, and empty or loading states. + +Create a new pattern only when reuse would produce awkward semantics or poor usability. + +## Non-goals + +Avoid pushing the interface toward: + +- bright startup-dashboard aesthetics +- highly animated consumer-product styling +- oversized rounded cards everywhere +- generic marketing-site gradients disconnected from the product +- decorative icons or illustrations that compete with data + +## Update protocol + +When a design decision changes: + +1. update the implementation +2. update this file in the same PR +3. note the new default pattern instead of documenting one-off exceptions + +If the code and this file disagree, align them quickly. Long-lived mismatches will turn this document into stale theory, which makes it useless.