Neon-Desk/docs/DESIGN_SYSTEM.md

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/index-card-row.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.