453 lines
15 KiB
Markdown
453 lines
15 KiB
Markdown
# 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.
|