Jyotisha/frontend/DESIGN.md

Jyotisha Web Design System

This file adapts the full visual analysis in CLAUDE_DESIGN.md to the shipped Jyotisha application. CLAUDE_DESIGN.md remains the upstream reference; this file is the implementation contract.

1. Atmosphere & Identity

Jyotisha feels like a private reading room: warm, editorial, grounded, and quiet enough for reflective conversation. The signature is a parchment canvas paced by terracotta actions and deep ink product surfaces, with serif display type giving astrological guidance the gravity of a considered essay rather than a generic chatbot.

2. Color

Palette

Role	Token	Value	Usage
Canvas	--color-canvas	#faf9f5	Page floor, inputs, light controls
Soft canvas	--color-canvas-soft	#f5f0e8	Secondary bands, table rows
Card surface	--color-canvas-muted	#efe9de	Feature cards, user messages, selected rows
Strong cream	--color-canvas-strong	#e8e0d2	Pressed and emphasized neutral surfaces
Ink	--color-ink	#141413	Headlines and primary text
Body	--color-ink-strong	#252523	Strong body copy
Secondary text	--color-ink-secondary	#6c6a64	Supporting copy and labels
Tertiary text	--color-ink-tertiary	#8e8b82	Hints and metadata
Primary action	--color-action	#cc785c	Primary buttons and high-signal links
Primary active	--color-action-hover	#a9583e	Hover and pressed action
Dark surface	--color-surface-dark	#181715	Sidebar and dark product panels
Dark raised	--color-surface-dark-raised	#252320	Selected navigation and nested dark surfaces
Dark soft	--color-surface-dark-soft	#1f1e1b	Dark secondary panels
On dark	--color-on-dark	#faf9f5	Primary text on dark surfaces
On dark muted	--color-dark-muted	#a09d96	Secondary text on dark surfaces
Hairline	--color-border	#e6dfd8	Default separators and controls
Strong hairline	--color-border-strong	#cfc5b8	Inputs and higher-contrast dividers
Success	--color-success	#5d9b6a	Available and completed states
Warning	--color-warning	#b07b22	Caution states
Error	--color-danger	#c64545	Errors and destructive actions
Accessible focus	--color-focus	#a9583e	Keyboard focus and input focus

Rules: neutrals stay warm; the action color is scarce; dark surfaces provide pacing rather than a second theme. No raw color may appear in UI styles outside these tokens and their documented alpha mixes.

3. Typography

Font stacks

• Display: "Tiempos Headline", "Songti SC", "STSong", "Noto Serif CJK SC", Georgia, serif. The licensed Copernicus/Tiempos files are unavailable; the Chinese Song serif stack is the declared production substitute.
• Body/UI: StyreneB, Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif.
• Code/data: "JetBrains Mono", "SFMono-Regular", Consolas, monospace.

Scale

Token	Size	Weight	Line height	Tracking	Usage
--type-display-lg	48px	400	1.1	-1px	Desktop page titles
--type-display-md	36px	400	1.15	-.5px	Dialog and mobile page titles
--type-display-sm	28px	400	1.2	-.3px	Section titles
--type-title-lg	22px	500	1.3	0	Prominent UI titles
--type-title-md	18px	500	1.4	0	Card and message headings
--type-title-sm	16px	500	1.4	0	List titles
--type-body-md	16px	400	1.55	0	Default reading text
--type-body-sm	14px	400	1.55	0	Compact UI text
--type-caption	13px	500	1.4	0	Labels and metadata
--type-overline	12px	500	1.4	1.5px	Eyebrows and badges

Display headings use the serif stack at weight 400. Body copy never drops below 14px; 12–13px is reserved for short labels and metadata. CJK text uses text-wrap: pretty; display text uses text-wrap: balance.

4. Spacing & Layout

The base unit is 4px. Tokens are --space-1: 4px, --space-2: 8px, --space-3: 12px, --space-4: 16px, --space-5: 20px, --space-6: 24px, --space-8: 32px, --space-10: 40px, --space-12: 48px, --space-16: 64px, and --space-24: 96px.

• Chat reading width: 760px for the welcome/composer and 900px for long answers.
• Admin content width: 1200px, centered.
• Desktop shell: 288px sidebar plus flexible reading panel.
• Breakpoints: mobile below 768px, tablet 768–1023px, desktop 1024px and above.
• All full-height surfaces use 100dvh. Touch targets are at least 44px.

5. Components

Brand mark

• Structure: image-backed mark plus serif wordmark.
• Variants: light canvas, dark sidebar.
• States: static; never animated.
• Accessibility: decorative image is hidden when adjacent text names the product.

Button

• Variants: coral primary, cream secondary, text, circular icon, dark-surface neutral.
• Spacing: 44px minimum height; radii 8px for standard and full radius for icon-only.
• States: default, hover, active, focus-visible, disabled, loading.
• Motion: 120ms transform/color; active translates by 1px or scales to .98.

Input and composer

• Structure: warm canvas field, hairline, typed value, optional icon action.
• States: default, hover, focus with terracotta ring, disabled, invalid, loading.
• Accessibility: persistent label where practical; composer has an explicit accessible label.

Navigation item

• Structure: title, optional metadata, current-state marker.
• States: default, hover, current, focus, disabled.
• Surface: dark sidebar; current uses raised dark surface and terracotta marker.

Message

• Variants: assistant editorial text on canvas; user text on warm card surface; streaming; error.
• Identity: every assistant message carries the 32px Jyotisha logo avatar; user messages stay visually lighter and avatar-free.
• Typography: assistant body 16px with serif subheadings; user body 14px.
• Suggestions: keep follow-up actions compact, with 8px internal horizontal padding and a narrower 680px group width.
• Motion: new messages enter with a short opacity/translate transition only.

Suggestion card

• Structure: topic label, question, directional icon. Categories are not numbered because they have no required order. At tablet widths, the cards stack into one column so Chinese questions keep natural phrase boundaries beside the persistent sidebar.
• Surface: warm card; three responsive editorial cards rather than a generic equal feature row.
• States: default, hover, active, focus, disabled, loading, fallback notice.

Start greeting

• Content: invite the user to ask what matters now; do not repeat that birth data is ready or explain setup state.
• Timing: use the browser's local hour: morning 05:00–10:59, noon 11:00–13:59, afternoon 14:00–17:59, evening 18:00–22:59, and late night 23:00–04:59.
• Variation: each time band has three concise prompts; select one once per visit so re-renders do not change the sentence.

Account sheet

• Structure: title, account summary, redeem section, profile form, actions.
• Surface: canvas sheet over warm scrim; sections separated by hairlines.
• States: closed, opening, open, validation error, success, saving.

Admin panel and data table

• Structure: editorial header, cream form panels, dark data surface.
• States: loading, empty, populated, generated codes, error, copy success.
• Responsive: form collapses to two columns then one; table scrolls horizontally.

6. Motion & Interaction

Type	Duration	Easing	Usage
Micro	120ms	ease-out	Button and row feedback
Standard	180ms	cubic-bezier(.22, 1, .36, 1)	Sheet, sidebar, message entry
Emphasis	360ms	cubic-bezier(.16, 1, .3, 1)	Loading mark only

Only transform, opacity, and color/filter transitions animate. Reduced-motion disables non-essential animation. Motion communicates state; decorative looping is limited to an active loading state.

7. Depth & Surface

Strategy: mixed tonal shifts with warm hairlines. Most depth comes from canvas, cream card, dark surface, and terracotta alternation. Standard UI uses no drop shadow. Modal and raised-sheet depth use one restrained two-stage token: --shadow-elevated: 0 1px 2px rgba(20, 20, 19, .08), 0 12px 28px -16px rgba(20, 20, 19, .22). Interactive rings use 0 0 0 1px or the focus ring; no generic card shadows or atmospheric gradients.