# 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.

### Research workspace modes

The research product now supports two layout modes for the same ticker-scoped workspace:

- `Workspace`: the default operating mode. Keep memo authoring, library management, and uploads in the primary column with the copilot docked as a sticky secondary rail.
- `Copilot Focus`: a deep-work mode. The conversation becomes the primary surface and memo, library, and packet views move into secondary tabs.

Rules:

- The active ticker must remain visible in both modes.
- Mode switches should preserve the same local state, draft state, and copilot session.
- Secondary surfaces in focus mode should feel adjacent, not modal. Use tabbed panel switching rather than route changes for memo, library, and packet context.
- Avoid introducing a second page shell for focus mode. The user should feel they are still inside the research workspace.

## 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`

### Research copilot panels

Copilot surfaces should feel like analytical instruments, not consumer chat.

Use the docked copilot rail for:

- cited Q&A tied to the current ticker
- short follow-up turns during memo work
- pinning or attaching evidence while staying in the main workspace

Use the focus copilot surface for:

- multi-turn investigative sessions
- long answers with multiple citations
- review-first drafting into memo or notes

Copilot panel rules:

- Keep header copy operational and concise.
- Show context chips for ticker, target memo section, and pinned evidence count.
- Source toggles should be compact and behave like tool filters, not marketing pills.
- Message cards should differentiate user and assistant turns with surface treatment, not bright color.
- Empty states should suggest concrete research questions rather than generic onboarding copy.

### Citation cards

Citation cards are evidence controls, not decorative footnotes.

Rules:

- Lead with the citation index and source label.
- Keep excerpts short and scan-friendly.
- Present actions inline: `Open`, `Pin` or `Unpin`, and `Attach`.
- Use the same card rhythm inside docked and focus copilot modes.
- If a citation cannot be attached because no artifact exists, disable the attach action instead of hiding it.

### Review-first AI write flows

AI-generated content may propose note drafts, memo-section drafts, or background brief jobs, but it must not silently mutate user-authored research state.

Rules:

- Suggested actions should be explicit buttons on assistant messages.
- Drafting into notes or memo sections should populate editable client form state first.
- Persistence should happen only through the existing note or memo save actions.
- Long-running synthesis should route through the task/notification system instead of blocking the conversation thread.

### 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.