oh-my-design-cli 1.0.1 → 1.1.0

package/references/dcard/DESIGN.md

@@ -1,302 +0,0 @@
-# Design System Inspiration of Dcard
-
-## 1. Visual Theme & Atmosphere
-
-Dcard is Taiwan's largest anonymous social platform — and its design system is an exemplar of **Material Design adapted for East-Asian forum culture**. The page chrome is wrapped in a deep teal-navy (`#00324e`) header bar that frames a **clean light-gray content surface** (`#f2f2f2`), inside which posts sit on **pure white cards** (`#ffffff`). This editorial framing — dark exterior, clean interior — distinguishes Dcard from the all-light Western social platforms (Reddit, Facebook) and the all-dark gamer-chic alternatives. It feels closer to a curated digital magazine than an open feed.
-
-Typography is **Roboto-led** with comprehensive Traditional Chinese fallbacks (`Roboto, "Helvetica Neue", Helvetica, Arial, "PingFang TC", 黑體-繁, "Heiti TC", 蘋果儷中黑, "Apple LiGothic Medium", 微軟正黑體, "Microsoft JhengHei"`). Headlines use **weight 500 (medium)**, not 700 — a Material Design convention that creates hierarchy through subtle weight shifts and color (`rgba(0,0,0,0.85)` for primary text). The typography scale is exhaustive: 4 headline tiers (32/28/24/20px), title (18px/600), 2 subtitles (16/14px/500), 2 body sizes (16/14px/400), and 2 caption sizes (12/10px/500).
-
-What truly distinguishes Dcard is the **breadth of its semantic token system**. The site exposes 200+ CSS custom properties on `:root`, organized into clear namespaces: `--color-dcard-*` for brand, `--color-state-*` for status, `--color-text-*` for foreground, `--color-bg-*` for surfaces, `--color-gender-*` for forum-specific identity colors (a unique reflection of Dcard's gender-tagged posting culture), `--shadow-level-1` through `--shadow-level-5` for elevation, `--vars-*` for layout sizing, and `--animations-*` for motion. This isn't an internal-only design system — it's a public, semantically-named token layer that any agent can read directly from the live site.
-
-**Key Characteristics:**
-- Roboto-led typography stack with full Traditional Chinese (`PingFang TC`, `Heiti TC`, `微軟正黑體`) fallbacks
-- **Weight 500 (medium)** as the headline default — Material Design convention, not bold-700
-- 200+ semantic CSS custom properties exposed on `:root` (effectively a public design system)
-- Deep teal-navy header (`#00324e`) framing a light-gray content area (`#f2f2f2`) with white post cards
-- Blue-monochrome brand palette: primary `#3397cf`, secondary `#006aa6`, tertiary `#00324e`
-- 5-level Material elevation shadow system (`--shadow-level-1` to `--shadow-level-5`)
-- Material Design easing curve: `cubic-bezier(.4, 0, .2, 1)` with `.15s` short / `.3s` medium durations
-- Unique **gender-coded color tokens** (`--color-gender-female: #cb3a6b`, `--color-gender-male: #1c7fac`) reflecting forum culture
-- **Gold premium accent** (`#ffc51b`) reserved for subscription/premium features
-- **Topic purple** (`#bf8ff0`) for cross-cutting interest groups
-- 8px border-radius is the default (buttons, cards, chips); `--vars-max-page-width: 1280px` with 728px main content + 300px aside
-
-## 2. Color Palette & Roles
-
-Dcard exposes its color system via CSS custom properties on `:root`. All values below are extracted directly.
-
-### Brand
-- **Dcard Primary** (`#3397cf`): `--color-dcard-primary`. Main brand blue. Used for primary CTAs (Download App), brand icons, link accents.
-- **Dcard Primary Hover** (`#5ab0db`): `--color-dcard-primary-hover`. Lighter blue for hover states.
-- **Dcard Secondary** (`#006aa6`): `--color-dcard-secondary`. Deeper supporting blue, used in search submit buttons and active states.
-- **Dcard Tertiary** (`#00324e`): `--color-dcard-tertiary`. The signature deep teal-navy. Used as the page header bg, sidebar hover bg (`--color-bg-sidebar-hover: #032133`), and brand chrome.
-- **Dcard Hint** (`#e7f3f9`): `--color-dcard-hint`. Very light blue tint for hover backgrounds and subtle highlights.
-- **Dcard Premium** (`#ffc51b`): `--color-dcard-premium`. Gold for premium subscribers and paid features.
-- **Dcard Premium Hover** (`#ffd558`): `--color-dcard-premium-hover`.
-
-### State (Status)
-- **Success** (`#49bd69`): `--color-state-success`. Hover `#6fc985`, active `#339653`.
-- **Danger** (`#ea5c5c`): `--color-state-danger`. Hover `#f78c88`, active `#c44347`.
-- **Reminder / Warning** (`#f0a955`): `--color-state-reminder`. Hover `#f0b941`, active `#da9246`.
-
-### Backgrounds (Surfaces)
-- **Bg Base 1** (`#f2f2f2`): `--color-bg-base-1`. Default page content background — the gray frame inside the navy header.
-- **Bg Base 2** (`#ffffff`): `--color-bg-base-2`. Card surface, post background.
-- **Bg Base 3** (`#ffffff`): `--color-bg-base-3`. Same as base 2; reserved for layered cards.
-- **Bg Light** (`#ffffff`): `--color-bg-light`. Pure white, modal/dropdown surfaces.
-- **Bg Dark** (`#000000`): `--color-bg-dark`. Reserved for inverted contexts.
-- **Bg Container** (`#0000000d`): `--color-bg-container`. Black 5% — chip backgrounds on light surfaces.
-- **Bg Special** (`#f0b941`): `--color-bg-special`. Same as reminder hover — used for promotional/sponsored chips.
-- **Bg Topic** (`#bf8ff0`): `--color-bg-topic`. Lavender-purple for topic tags (cross-cutting interest groups).
-- **Bg Snackbar** (`#2c2c2c`): `--color-bg-snackbar`. Dark gray for toast notifications.
-- **Bg Sidebar Hover** (`#032133`): `--color-bg-sidebar-hover`. Slightly darker than tertiary for sidebar item hover.
-- **Bg Chip on Dark** (`#ffffff14`): `--color-bg-chip-on-dark`. White 8% for chips on the navy header.
-- **Bg Spotlight** (`#00000059`): `--color-bg-spotlight`. Black 35% — modal backdrop.
-- **Bg Sign-up Overlay** (`#000000b3`): `--color-bg-sign-up-overlay`. Black 70% — full-page CTA overlay.
-- **Bg Btn Disabled** (`#e0e0e0`): `--color-bg-btn-disabled`.
-- **Shimmer Bg / Fg** (`#f2f2f2` / `#fafafa`): Loading skeleton colors.
-
-### Text (Foreground)
-- **Text Primary** (`#000000d9`): `--color-text-primary`. Black at 85% opacity. Used for headings, post titles, primary body text.
-- **Text Secondary** (`#00000080`): `--color-text-secondary`. Black at 50%. Captions, timestamps, metadata.
-- **Text Hint** (`#00000059`): `--color-text-hint`. Black at 35%. Placeholder hints.
-- **Text Disabled** (`#0003`): `--color-text-disabled`. Black at 20%.
-- **Text Light Primary** (`#ffffff`): `--color-text-light-primary`. White text on the navy header.
-- **Text Light Secondary** (`#ffffff8c`): `--color-text-light-secondary`. White at 55% on dark surfaces.
-- **Text Light Hint** (`#fff6`): `--color-text-light-hint`. White at 40%.
-- **Text Dark Primary / Secondary**: Same as primary / secondary, semantic aliases.
-- **Text Default Hovered** (`#00000059`): `--color-text-default-hovered`.
-
-### Borders & Separators
-- **Border** (`#cacaca`): `--color-border`. Standard component border (inputs, dividers).
-- **Border Disabled** (`#e0e0e0`): `--color-border-disabled`.
-- **Separator** (`#0000001a`): `--color-separator`. Black 10% — row dividers on light surfaces.
-- **Separator on Dark** (`#ffffffb3`): `--color-separator-on-dark`. White 70% — separators on the navy header.
-
-### Gender-Coded (Unique to Dcard)
-A reflection of Dcard's posting culture, where many forums (女孩 / 男生 / 心情) display gender-tagged author chips:
-- **Female** (`#cb3a6b`): `--color-gender-female`. Light variant `#f48fb1`.
-- **Male** (`#1c7fac`): `--color-gender-male`. Light variant `#81d4fa`.
-- **Other** (`#2c2c2c`): `--color-gender-other`. Light variant `#e0e0e0`.
-
-### Icon & Misc
-- **Icon Button** (`#000000b3`): `--color-icon-button`. Black 70% — default icon color on light surfaces.
-- **Crop Mask** (`#000000b3`): `--color-crop-mask`. Modal/crop UI backdrop.
-- **Brand Sponsor Hovered** (`#fcd46d`): `--color-brand-sponsor-hovered`. Sponsored content highlight.
-
-## 3. Typography Rules
-
-### Font Stack
-```
-Roboto, "Helvetica Neue", Helvetica, Arial, "PingFang TC", 黑體-繁, "Heiti TC", 蘋果儷中黑, "Apple LiGothic Medium", 微軟正黑體, "Microsoft JhengHei", sans-serif
-```
-
-Roboto leads (Material Design convention), with full Traditional Chinese fallbacks for native rendering on TW/HK Chrome environments.
-
-### Type Scale (verified from `:root` CSS custom properties)
-
-| Role | Token | Size | Weight | Line Height |
-|---|---|---|---|---|
-| Headline 1 | `--typography-headline-1-font-size` | `32px` (mobile `30px`) | `500` | `42px` (mobile `40px`) |
-| Headline 2 | `--typography-headline-2-font-size` | `28px` (mobile `24px`) | `500` | `40px` (mobile `33px`) |
-| Headline 3 | `--typography-headline-3-font-size` | `24px` (mobile `20px`) | `500` | `28px` |
-| Headline 4 | `--fonts-headline-4-font-size` | `20px` | `500` | `28px` |
-| Title | `--typography-title-font-size` | `18px` | `600` | `25px` |
-| Subtitle 1 | `--typography-subtitle-1-font-size` | `16px` | `500` | `22px` |
-| Subtitle 2 | `--typography-subtitle-2-font-size` | `14px` | `500` | `20px` |
-| Body 1 | `--typography-body-1-font-size` | `16px` | `400` | `22px` |
-| Body 1 (lh-28 variant) | `--typography-body-1-lh-28-font-size` | `16px` | `400` | `28px` (article reading) |
-| Body 2 | `--typography-body-2-font-size` | `14px` | `400` | `20px` |
-| Caption | `--typography-caption-font-size` | `12px` | `500` | `17px` |
-| Caption 2 | `--typography-caption-2-font-size` | `10px` | `500` | `16px` |
-
-### Conventions
-- **Weight 500 (medium)** is the headline default — never weight 700/800 like commerce or news sites. Material Design heritage.
-- **Title is the only weight-600 tier** — used sparingly for section headers in modals and editors.
-- **Body uses weight 400** — captions and small labels jump to weight 500 to remain readable at small sizes.
-- **Mobile sizes step down by ~20%** for headlines but stay identical for body and below.
-- **Line-heights are generous** (1.3–1.4× ratio for body, ~1.4× for headlines) — supports CJK glyph density.
-
-## 4. Component Stylings
-
-### Buttons
-**Default radius**: `8px` (verified across multiple button variants on the site).
-
-| Variant | Bg | Text | Notable |
-|---|---|---|---|
-| Primary CTA (Download App) | `#3397cf` (`--color-dcard-primary`) | `#ffffff` | Weight 500, 14px |
-| Secondary CTA (search submit) | `#006aa6` (`--color-dcard-secondary`) | `#ffffff` | Often joined to input → `border-radius: 0px 4px 4px 0px` |
-| Counter / Action (584, 179 likes) | transparent | `rgba(0,0,0,0.5)` | 8px radius, 14px weight 500 |
-| Disabled | `#e0e0e0` (`--color-bg-btn-disabled`) | secondary text | |
-
-Padding patterns: `1px 14px` (small), `8px 20px` (medium for search submit).
-
-### Cards (Post Entry)
-- White bg (`#ffffff` = `--color-bg-base-2`)
-- Sit on the gray content background (`#f2f2f2`) → contrast handles separation, no border needed
-- `--vars-min-post-list-section-width: 728px` defines the main feed width
-- `--vars-post-entry-padding: 20px` for inner spacing
-- `--vars-post-entry-thumbnail-size: 84px` for inline thumbnails
-- Cross-post variants use `--vars-post-entry-cross-post-thumbnail-size: 66px`
-- Forum cards have explicit dimensions: `--vars-forum-card-width: 146px`, `--vars-forum-card-height: 110px`
-
-### Header / Navigation
-- **Header**: `--vars-header-height: 48px`, `--vars-header-padding: 20px`, bg `#00324e` (tertiary), white text
-- **Logo + Search + Sign In/Up + Download App**: horizontal layout
-- **Search input**: White bg, pill-leaning corners (left 0px, right 8px when joined with submit)
-- **Left Sider** (forum nav): `--vars-my-page-sider-width: 208px`, light bg, icon + text rows
-- **Right Aside** (widgets/ads): `--vars-forum-aside-section-width: 300px`, `--vars-forum-aside-section-gap: 10px`
-
-### Tabs (All / Following)
-- Underline-driven indicator
-- Active tab: text color `--color-text-primary` (`#000000d9`)
-- Inactive: `--color-text-secondary` (`#00000080`)
-- Tab header height: `--vars-tabview-header-height: 48px`
-
-### Chips / Topics
-- Topic chips: bg `#bf8ff0` (`--color-bg-topic`), white text — lavender accent
-- Sponsor/special chips: bg `#f0b941` (`--color-bg-special`)
-- On-dark chips: bg `#ffffff14` (`--color-bg-chip-on-dark`)
-- Topic spacing: `--vars-topic-gap: 8px`
-- Topic list height: `--vars-topic-list-height: 60px`
-
-### Snackbar / Toast
-- Bg `#2c2c2c` (`--color-bg-snackbar`)
-- White text (`--color-text-light-primary`)
-- Bottom positioning: `--vars-toast-bottom: 0px`, `--vars-toast-width: 250px`
-- With bottom bar: `--vars-snackbar-bottom-with-bottom-bar: 16px`
-
-### Modals
-- Post modal: `--vars-post-modal-width: 728px`
-- Comment modal: `--vars-comment-modal-width: 720px`
-- Backdrop: `--color-bg-spotlight` (`#00000059`) or `--color-mask` (`#0006`)
-
-### Sign-Up Overlay
-- Full-page bg: `--color-bg-sign-up-overlay` (`#000000b3`, black 70%)
-- Triggers after scroll/engagement to encourage account creation
-
-## 5. Layout Principles
-
-### Page Structure
-- **Max page width**: `--vars-max-page-width: 1280px`
-- **Three-column layout**:
-  - Left sider (forum nav): `208px` (`--vars-my-page-sider-width`)
-  - Main content (post list): `728px` (`--vars-min-post-list-section-width`)
-  - Right aside (widgets/ads): `300px` (`--vars-forum-aside-section-width`)
-- Sections gap: `--vars-forum-sections-gap: 12px`
-
-### Spacing
-- **Header padding**: `20px`
-- **Post entry padding**: `20px`
-- **Post view padding**: `20px` vertical, `24px` horizontal
-- **Post list section padding**: `20px` vertical, `24px` horizontal
-- **Columns item horizontal**: `24px`
-- Content title height: `60px` (`--vars-my-page-content-title-height`)
-
-### Density
-Dcard is **medium-density**. Posts are visually distinct (white card on gray bg), but the 728px main column packs efficiently — title + preview + thumbnail + actions in a single horizontal row at desktop sizes. Not as dense as Pinkoi commerce, not as airy as Medium articles.
-
-## 6. Depth & Elevation
-
-Dcard uses a **Material Design-style 5-level shadow system**, all keyed off black with low alpha for soft, neutral elevation.
-
-| Level | Token | Value | Use |
-|---|---|---|---|
-| 1 | `--shadow-level-1` | `0px 1px 6px -2px #00000052` | Subtle lift (chips, hover cards) |
-| 2 | `--shadow-level-2` | `0px 2px 8px -1px #0003` | Default card, dropdown |
-| 3 | `--shadow-level-3` | `0px 3px 12px #0000002e` | Elevated card, popover |
-| 4 | `--shadow-level-4` | `0px 4px 16px #00000029` | Modal, sticky bar |
-| 5 | `--shadow-level-5` | `0px 6px 24px #0000001f` | Highest elevation: dialogs, full-screen overlays |
-
-Note: Most post cards on the feed sit **flat without shadow** — the content area (`#f2f2f2`) provides separation against white cards via contrast. Shadows are reserved for genuinely floating elements.
-
-### Z-Index
-- Header is sticky and sits above content
-- Modals use `--color-bg-spotlight` backdrop
-- Sign-up overlay (`--color-bg-sign-up-overlay`) sits above all chrome
-- Toast/snackbar at the highest level
-
-### Animation
-- Easing: `--animations-bezier: cubic-bezier(.4, 0, .2, 1)` — Material Design standard easing curve
-- Short duration: `--animations-short-duration: .15s` (hover, press)
-- Medium duration: `--animations-medium-duration: .3s` (page transitions, accordions)
-
-## 7. Do's and Don'ts
-
-- **DO** use weight 500 (medium) for headlines. Dcard never goes weight 700 — Material Design convention.
-- **DON'T** use weight 700 except in legacy or one-off display contexts.
-- **DO** use the semantic color token namespace: `--color-dcard-*` for brand, `--color-state-*` for status, `--color-text-*` for foreground, `--color-bg-*` for surfaces.
-- **DON'T** introduce ad-hoc hex values. Dcard's 200+ tokens cover virtually every UI surface.
-- **DO** wrap the page in the deep navy header (`#00324e`) and place content on the gray base (`#f2f2f2`) with white cards. The chrome/content contrast is the brand signature.
-- **DON'T** use white-on-white nesting — the `#f2f2f2` content layer is what separates white cards visually.
-- **DO** use `8px border-radius` as the default for buttons, cards, and chips.
-- **DON'T** use 4px or sharp corners — Dcard's softer 8px radius is the brand's tactile signature.
-- **DO** use `--shadow-level-2` (`0px 2px 8px -1px #0003`) for default cards that need elevation. Use higher levels only for genuinely floating UI.
-- **DON'T** apply heavy shadows to feed posts — let the gray/white contrast separate them.
-- **DO** use the gender colors (`--color-gender-female`, `--color-gender-male`, `--color-gender-other`) for author chips on gender-tagged posts. This is a culturally significant part of Dcard's UX.
-- **DON'T** use gender colors for non-author contexts — it conflates identity with status.
-- **DO** reserve gold (`#ffc51b`, `--color-dcard-premium`) for premium/subscription features only.
-- **DON'T** use premium gold for warnings or general highlights — it weakens the subscription signal.
-- **DO** use Material easing `cubic-bezier(.4, 0, .2, 1)` with `.15s` for hover/press and `.3s` for page transitions.
-- **DON'T** use bouncy/elastic easing — Dcard's motion is restrained and platform-native.
-
-## 8. Responsive Behavior
-
-### Breakpoints (inferred from mobile-specific tokens)
-Dcard provides explicit mobile typography sizes via `--typography-*-font-size-mobile` tokens, indicating a clear breakpoint at the tablet/mobile boundary (typically 768px in Material conventions).
-
-| Width | Behavior |
-|---|---|
-| Desktop `>1280px` | Centered max-width container, three-column layout (208 / 728 / 300) |
-| Desktop `1024–1280px` | Three-column compresses, asides may collapse |
-| Tablet `768–1024px` | Right aside hidden, two-column (sider + main) |
-| Mobile `<768px` | Single column. Headlines step down: H1 32px → 30px, H2 28px → 24px, H3 24px → 20px |
-
-### Touch & Mobile
-- Bottom navigation height token: `--vars-bottom-navigation-height: 0px` on web (used in app webviews)
-- Safe area inset: `--safe-area-inset-bottom: 0px` (notch handling)
-- Forum hero image: `--vars-forum-hero-image-height: 243px`
-
-### Media Caps
-- `--vars-max-post-media-vh: 60vh` — embedded videos/images cap at 60% viewport height
-- Cover image: `width: 100%`, `object-fit: cover`, `height: 100%` (`--mixins-cover-image-*`)
-
-### Text Truncation
-- Single-line ellipsis: `--mixins-ellipsis-overflow: hidden; --mixins-ellipsis-text-overflow: ellipsis; --mixins-ellipsis-white-space: nowrap`
-- Multi-line clamp: `--mixins-multi-ellipsis-display: -webkit-box`, `--mixins-multi-ellipsis--webkit-box-orient: vertical`, `--mixins-multi-ellipsis--webkit-line-clamp: 1`
-- Line-clamp value can be customized per component
-
-## 9. Agent Prompt Guide
-
-### Quick Color Reference
-- Primary CTA: `--color-dcard-primary` (`#3397cf`); hover `#5ab0db`
-- Secondary CTA: `--color-dcard-secondary` (`#006aa6`)
-- Page chrome (header bg): `--color-dcard-tertiary` (`#00324e`)
-- Page content bg: `--color-bg-base-1` (`#f2f2f2`)
-- Card / surface: `--color-bg-base-2` (`#ffffff`)
-- Primary text: `--color-text-primary` (`#000000d9`, black 85%)
-- Secondary text: `--color-text-secondary` (`#00000080`, black 50%)
-- Border: `--color-border` (`#cacaca`)
-- Separator: `--color-separator` (`#0000001a`, black 10%)
-- Premium: `--color-dcard-premium` (`#ffc51b`) — subscription only
-- Topic accent: `--color-bg-topic` (`#bf8ff0`)
-- Success / Danger / Reminder: `#49bd69` / `#ea5c5c` / `#f0a955`
-
-### Example Component Prompts
-- "Create a Dcard-style post card: white bg (`#ffffff`), no border, no radius (sits on gray `#f2f2f2` page bg). Inner padding 20px. Layout: avatar (40px circle) + forum name (12px weight 500 colored per forum) + timestamp (12px weight 500 `#00000080`) on top row, post title H4 size (20px weight 500 `#000000d9`) on second row, body preview (14px weight 400 `#00000080` 2-line clamp), inline thumbnail (84px), action buttons (heart/comment/save/share) at bottom."
-- "Build a Dcard primary button: bg `#3397cf`, white text, 8px border-radius, 14px weight 500, padding `8px 20px`. Hover: bg `#5ab0db`. Active: darken further. No shadow. Transition: `background .15s cubic-bezier(.4, 0, .2, 1)`."
-- "Design the Dcard header: full-width sticky bar, height 48px, bg `#00324e` (tertiary navy), white logo on left (28px height), search input center (white bg, 8px radius left side, joined search submit `#006aa6` on right with `0px 8px 8px 0px` radius), Sign in/Sign up text link + Download App button (`#3397cf` bg, white text, 8px radius) on right."
-- "Create a topic chip: bg `#bf8ff0` (lavender purple), white text, 12px weight 500, 8px radius, padding `4px 10px`. Use only for cross-cutting topics (e.g., '#study tips', '#dating advice')."
-- "Build a sign-up overlay CTA: full-page absolute overlay with `#000000b3` (black 70%) bg, centered content card (white, 8px radius, `0px 6px 24px #0000001f` shadow level 5), heading 'From school to work, find your resonance on Dcard.' (24px weight 500 `#000000d9`), subhead 14px weight 400 `#00000080`, two buttons: Sign in (white border ghost) + Sign up (`#3397cf` filled). Triggers after 2 scroll lengths."
-
-### Iteration Guide
-1. **Always reference CSS variables, not hex values** — Dcard's design system is its `:root` token layer. `--color-dcard-primary` is more durable than `#3397cf`.
-2. **Default headline weight is 500, never 700**. Dcard is Material Design-aligned.
-3. **`8px` radius everywhere** (buttons, cards, chips). Don't use 4px or pill shapes.
-4. **Wrap page in `#00324e` chrome + content on `#f2f2f2` + white cards** — this is the visual signature.
-5. **Five shadow levels exist (`--shadow-level-1` to `-5`)** — use level 2 for cards by default, escalate only for floating UI.
-6. **Roboto first, then Traditional Chinese fallbacks** — never hardcode `font-family` without including the TC stack.
-7. **Material easing `cubic-bezier(.4, 0, .2, 1)`** with `.15s` (hover/press) or `.3s` (transitions). Don't use bounce.
-8. **Gender colors (`--color-gender-*`) only for author chips** on gender-tagged forums (女孩/男生/感情). Never repurpose.
-9. **Premium gold (`#ffc51b`) only for subscription/premium UI**. It's a finite signal.
-10. **Three-column layout 208 / 728 / 300** at desktop. Right aside drops first on tablet, sider drops on mobile.

package/references/freee/DESIGN.md

@@ -1,308 +0,0 @@
-# Design System Inspiration of freee
-
-## 1. Visual Theme & Atmosphere
-
-freee is Japan's leading cloud accounting / HR / payroll SaaS, and its design system **Vibes** is fully open-source at [github.com/freee/vibes](https://github.com/freee/vibes). The token files (`stylesheets/lv0/_colors.scss`, `_size.scss`, `_fonts.scss`) form a clean, semantic, three-tier architecture: **scale tokens** (`$vbColorsP01`–`P10` for primary blues, `S01`–`S10` for grayscale, etc.), **semantic tokens** (`$vbPrimaryColor`, `$vbAccentColor`, `$vbAlertColor`), and **component tokens** (line-height, font sizes mapped to typography roles). This is the cleanest token architecture among the OMD references — and it's all readable from one place.
-
-The brand is anchored in a **deep enterprise blue** (`#285ac8`, `$vbColorsP07`) — calm, trustworthy, financial-software professional. A lighter accent blue (`#73a5ff`, `$vbColorsP04`) handles secondary emphasis. The color system extends across 9 hue families (Primary, Secondary/gray, Red, Orange, Yellow, Yellow-Green, Green, Blue-Green, Purple, Gray) with each having 5-10 calibrated shades, giving designers a complete palette for status, illustrations, and category coding.
-
-Typography is a Japanese-first system stack: `-apple-system, BlinkMacSystemFont, 'Helvetica Neue', 'ヒラギノ角ゴ ProN', Hiragino Kaku Gothic ProN, Arial, 'メイリオ', Meiryo, sans-serif`. The brand wordmark uses Noto Sans CJK JP Medium loaded explicitly as `freee-logo`. The type scale is a tight 5-step rhythm (10 / 12 / 14 / 16 / 24dp), with mobile sizes stepping down for headline tiers. Spacing follows a consistent 4dp baseline (4 / 8 / 16 / 24 / 32 / 48dp).
-
-**Key Characteristics:**
-- **Open-source design system** ([freee/vibes](https://github.com/freee/vibes)) with three-tier token architecture (scale → semantic → component)
-- Enterprise blue brand: `#285ac8` primary (`$vbColorsP07`), `#73a5ff` accent (`$vbColorsP04`)
-- 9-hue palette: Primary (P), Secondary/gray (S), Red (RE), Orange (OR), Yellow (YE), Yellow-Green (YG), Green (GR), Blue-Green (BG), Purple (PU), pure Gray (GY)
-- Each hue scale has 5-10 calibrated shades (P01 lightest → P10 darkest)
-- 4dp baseline spacing scale: `xs 4dp / s 8dp / basic 16dp / large 24dp / xl 32dp / xxl 48dp`
-- Tight 5-step type scale: `10 / 12 / 14 / 16 / 24dp` — no display extremes, no middle gaps
-- Form-control heights as design tokens: `small 24dp / basic 36dp / large 48dp`
-- Container max-width `1120dp` (`70rem`) — wider than Bootstrap defaults but narrower than Mercari
-- Three explicit shadow recipes: card, floating, popup (graduated weights)
-- Z-index hierarchy with semantic names: overlay 100 → form actions 200 → floating 500 → full-screen 700 → modal 1000 → popup 2000 → max
-- Japanese-first font stack with Hiragino Kaku Gothic ProN as the primary CJK fallback
-
-## 2. Color Palette & Roles
-
-All values extracted from `stylesheets/lv0/_colors.scss` in the open-source [freee/vibes](https://github.com/freee/vibes) repo (vibes_2021).
-
-### Primary Blue (`$vbColorsP01–P10`)
-- `#ebf3ff` (P01) — lightest tint, page background hint
-- `#dce8ff` (P02) — light surface, badge bg
-- `#aac8ff` (P03) — light accent
-- `#73a5ff` (P04) — **`$vbAccentColor`** (accent, hover for primary)
-- `#2864f0` (P05) — bright primary
-- `#3264dc` (P06) — primary mid
-- `#285ac8` (P07) — **`$vbPrimaryColor`** (primary actions, links, brand)
-- `#1e46aa` (P08) — primary dark
-- `#23418c` (P09) — primary darker
-- `#143278` (P10) — primary darkest
-
-### Secondary / Neutral (`$vbColorsS01–S10`)
-- `#f7f5f5` (S01) — `$vbColumnColor` (column / table bg)
-- `#f0eded` (S02) — `$vbBaseColor1` (subtle surface 1)
-- `#e9e7e7` (S03) — `$vbBaseColor2` (subtle surface 2)
-- `#e1dcdc` (S04)
-- `#d7d2d2` (S05)
-- `#bebaba` (S06)
-- `#aaa7a7` (S07)
-- `#8c8989` (S08) — `$vbBaseColor3` (mid neutral, captions)
-- `#6e6b6b` (S09) — `$vbBurntColor` (text-burnt)
-- `#464343` (S10) — darkest neutral
-
-### Status (Red, Orange, Yellow scales)
-- **Red** (`RE02 #fad2d7`, `RE04 #f07882`, `RE05 #dc1e32`, `RE07 #a51428`, `RE10 #6e0f19`)
-  - `$vbAlertColor: $vbColorsRE05` (`#dc1e32`) — alerts, errors, destructive actions
-- **Orange** (`OR02 #ffe1d2`, `OR04 #ffaa78`, `OR05 #fa6414`, `OR07 #be4b0f`, `OR10 #7d320a`)
-- **Yellow** (`YE02 #fff0d2`, `YE04 #ffd278`, `YE05 #ffb91e`, `YE07 #be8c14`, `YE10 #825a0f`)
-  - `$vbNoticeColor: $vbColorsYE07` (`#be8c14`) — warnings, notices
-
-### Yellow-Green / Green / Blue-Green (success, growth)
-- **Yellow-Green** (`YG02 #e6f0d2`, `YG04 #b4dc7d`, `YG05 #82c31e`, `YG07 #50961e`, `YG10 #3c5f14`)
-- **Green** (`GR02 #cdebd7`, `GR04 #64be8c`, `GR05 #00963c`, `GR07 #006e2d`, `GR10 #004b1e`) — success
-- **Blue-Green / Teal** (`BG02 #cdf0f0`, `BG04 #64d2d2`, `BG05 #00b9b9`, `BG07 #008c8c`, `BG10 #146464`)
-
-### Purple
-- `PU02 #e6d7fa`, `PU04 #b482f0`, `PU05 #733ce6`, `PU07 #5a2daa`, `PU10 #3c1e73`
-
-### Pure Gray (`$vbColorsGY01–GY10`)
-- `#fbfbfb` (GY01) — page bg highlight
-- `#dcdcdc` (GY02)
-- `#a0a0a0` (GY04)
-- `#5a5a5a` (GY05)
-- `#323232` (GY07) — **`$vbBlackColor`** (default text color)
-- `#1e1e1e` (GY10) — darkest gray
-
-### Semantic Aliases (the design contracts)
-| Semantic | Value | Use |
-|---|---|---|
-| `$vbPrimaryColor` | `$vbColorsP07` (`#285ac8`) | Primary CTAs, brand actions |
-| `$vbAccentColor` | `$vbColorsP04` (`#73a5ff`) | Accent hover, secondary brand |
-| `$vbLinkColor` | `$vbColorsP07` (`#285ac8`) | Hyperlinks (matches primary) |
-| `$vbColumnColor` | `$vbColorsS01` (`#f7f5f5`) | Table column bg |
-| `$vbBaseColor1` | `$vbColorsS02` (`#f0eded`) | Subtle surface 1 |
-| `$vbBaseColor2` | `$vbColorsS03` (`#e9e7e7`) | Subtle surface 2 |
-| `$vbBaseColor3` | `$vbColorsS08` (`#8c8989`) | Mid neutral text |
-| `$vbBurntColor` | `$vbColorsS09` (`#6e6b6b`) | Burnt-out text (de-emphasized) |
-| `$vbBlackColor` | `$vbColorsGY07` (`#323232`) | Default text color |
-| `$vbAlertColor` | `$vbColorsRE05` (`#dc1e32`) | Alerts, errors, destructive |
-| `$vbNoticeColor` | `$vbColorsYE07` (`#be8c14`) | Warnings, notices |
-| `$vbBackgroundColor` | `$vbColorsP01` (`#ebf3ff`) | Page tint background |
-
-### Scrim / Overlay
-- `$vbScrimColor: rgba(0, 0, 0, 0.5)` — modal backdrop
-- `$vbThinScrimColor: rgba(0, 0, 0, 0.12)` — light overlay (e.g., disabled state)
-
-## 3. Typography Rules
-
-### Font Stack
-```scss
-$vbFontFamily: '-apple-system', BlinkMacSystemFont, 'Helvetica Neue',
-  'ヒラギノ角ゴ ProN', Hiragino Kaku Gothic ProN, Arial, 'メイリオ', Meiryo,
-  sans-serif;
-```
-
-`-apple-system` and `BlinkMacSystemFont` lead for native rendering on macOS/iOS, then Helvetica Neue, then Japanese fallbacks (Hiragino → Meiryo). The brand wordmark uses **Noto Sans CJK JP Medium** loaded explicitly as `font-family: 'freee-logo'` from Google Fonts.
-
-### Type Scale (verified from `_size.scss`)
-| Token | Size | Use |
-|---|---|---|
-| `$vbFontSize0625` | `0.625rem` (10dp) | Smallest icon font |
-| `$vbFontSize0750` | `0.75rem` (12dp) | Caption |
-| `$vbFontSize0875` | `0.875rem` (14dp) | Normal body, Headline 3 |
-| `$vbFontSize1000` | `1rem` (16dp) | Headline 2 |
-| `$vbFontSize1500` | `1.5rem` (24dp) | Headline 1 |
-
-### Semantic Typography Tokens
-| Token | Value |
-|---|---|
-| `$vbCaptionFontSize` | `0.75rem` (12dp) |
-| `$vbNormalFontSize` | `0.875rem` (14dp) |
-| `$vbHeadline3FontSize` | `0.875rem` (14dp) |
-| `$vbHeadline2FontSize` | `1rem` (16dp) |
-| `$vbHeadline1FontSize` | `1.5rem` (24dp) |
-
-### Mobile Typography (steps down for tablets/phones)
-- `$vbMobileHeadline1FontSize: 16dp` (was 24dp)
-- `$vbMobileHeadline2FontSize: 14dp` (was 16dp)
-- `$vbMobileHeadline3FontSize: 14dp` (unchanged)
-
-### Line Height
-- `$vbLineHeight: 1.5` — universal default (generous for CJK readability)
-
-### Conventions
-- **No display sizes above 24dp** — freee's voice is utilitarian SaaS, not editorial
-- **Body and Headline 3 share 14dp** — visual hierarchy comes from weight + color, not size
-- **Mobile compresses everything to 14-16dp** — preserves 1.5 line-height for cramped screens
-- **Brand wordmark uses Noto Sans CJK JP Medium** — only place a custom font loads
-
-## 4. Component Stylings
-
-### Form Controls (heights are explicit tokens)
-| Token | Height | Use |
-|---|---|---|
-| `$vbFormControlSmallHeight` | `1.5rem` (24dp) | Compact inputs, dense tables |
-| `$vbFormControlHeight` | `2.25rem` (36dp) | Standard input, button |
-| `$vbFormControlLargeHeight` | `3rem` (48dp) | Hero CTAs, mobile-friendly forms |
-
-### Buttons
-- Primary: bg `#285ac8` (`$vbPrimaryColor`), white text, weight 500-700, default `36px` height (`$vbFormControlHeight`)
-- Padding follows the `xs/s/basic` spacing scale: `4px 16px` (small), `8px 16px` (basic), `12px 24px` (large)
-- Border-radius: not explicitly tokenized in vibes — components use `4px` as the de facto standard
-- Disabled: `$vbThinScrimColor` overlay (`rgba(0,0,0,0.12)`)
-
-### Inputs
-- Heights match `$vbFormControlHeight` tokens
-- Border: `1px solid $vbBaseColor3` (`#8c8989`)
-- Focus: border becomes `$vbPrimaryColor` (`#285ac8`)
-- Error: border becomes `$vbAlertColor` (`#dc1e32`), helper text in same red
-
-### Cards / Panels
-- Background: white (or `$vbColumnColor: #f7f5f5` for subtle differentiation)
-- Border: `1px solid $vbBaseColor2` (`#e9e7e7`)
-- Padding: `$vbBasicSize` (16dp) or `$vbLargeSize` (24dp)
-- Shadow: `$vbCardShadow` for elevated cards (see §6)
-
-### Tables
-- Column bg alternates: white / `$vbColumnColor` (`#f7f5f5`)
-- Row dividers: `1px solid $vbBaseColor2` (`#e9e7e7`)
-- Header: bold weight, dark text on white
-- Compact and dense — freee is enterprise productivity software
-
-### Navigation
-- Primary nav: white bg with subtle bottom border, `$vbPrimaryColor` for active link
-- Secondary nav: tab-style with underline indicator in `$vbPrimaryColor`
-
-### Status Badges
-- Success: `GR02` bg + `GR07` text (`#cdebd7` / `#006e2d`)
-- Alert: `RE02` bg + `RE05` text (`#fad2d7` / `#dc1e32`)
-- Notice: `YE02` bg + `YE07` text (`#fff0d2` / `#be8c14`)
-- Info: `P02` bg + `P07` text (`#dce8ff` / `#285ac8`)
-
-## 5. Layout Principles
-
-### Spacing Scale (verified from `_size.scss`)
-| Token | Value | dp |
-|---|---|---|
-| `$vbMinimum` | `1px` | 1px hairline |
-| `$vbXSmallSize` | `0.25rem` | 4dp |
-| `$vbSmallSize` | `0.5rem` | 8dp |
-| `$vbBasicSize` | `1rem` | 16dp |
-| `$vbLargeSize` | `1.5rem` | 24dp |
-| `$vbXLargeSize` | `2rem` | 32dp |
-| `$vbXXLargeSize` | `3rem` | 48dp |
-
-### Container
-- `$vbContainerSize: 70rem` (1120dp) — page max-width
-- Mobile breakpoint: `$vbMobileBoundaryWidth: 48rem` (768dp)
-
-### Density
-freee is **medium-density enterprise SaaS**. Forms breathe with `16dp` padding. Tables stay tight. Dashboards prefer 24-32dp section gaps. Avoid the high-density commerce aesthetic of Mercari/Pinkoi.
-
-## 6. Depth & Elevation
-
-### Three explicit shadow recipes (from `_colors.scss`)
-- **Card** — `$vbCardShadow`:
-  ```
-  0 0 1rem rgba(0, 0, 0, 0.1),
-  0 0.125rem 0.25rem rgba(0, 0, 0, 0.2)
-  ```
-- **Floating** — `$vbFloatingShadow`:
-  ```
-  0 0 1.5rem rgba(0, 0, 0, 0.1),
-  0 0.25rem 0.5rem rgba(0, 0, 0, 0.2)
-  ```
-- **Popup** — `$vbPopupShadow`:
-  ```
-  0 0 2rem rgba(0, 0, 0, 0.1),
-  0 0.375rem 0.75rem rgba(0, 0, 0, 0.2)
-  ```
-
-Each level uses the same dual-shadow technique (ambient diffuse + directional drop), scaling the radius progressively.
-
-### Z-Index Hierarchy (named tokens)
-| Token | Value | Use |
-|---|---|---|
-| `$vbOverlayZIndex` | `100` | Subtle overlays |
-| `$vbFormActionsZIndex` | `200` | Form action bars |
-| `$vbFloatingZIndex` | `500` | Floating cards |
-| `$vbFullScreenZIndex` | `700` | Full-screen views |
-| `$vbModalZIndex` | `1000` | Modals |
-| `$vbMessageModalZIndex` | `1500` | Message modals |
-| `$vbPopupZIndex` | `2000` | Popups |
-| `$vbPopupMessageZIndex` | `3000` | Popup messages |
-| `$vbFixedMessageZIndex` | `4000` | Fixed messages |
-| `$vbMaxZIndex` | `2147483647` | Maximum (system reserved) |
-
-### Animation
-Not explicitly tokenized in `_size.scss` extracted — components use SCSS-default transitions (`0.2-0.3s ease`).
-
-## 7. Do's and Don'ts
-
-- **DO** use the three-tier token system: scale (`$vbColorsP07`) → semantic (`$vbPrimaryColor`) → component-level. Always reference semantic over scale where possible.
-- **DON'T** invent new color values. The 9 hue scales × 5-10 shades cover virtually any need.
-- **DO** lead with `$vbPrimaryColor` (`#285ac8`) for brand actions and links. It's the same value — links should match buttons in this system.
-- **DON'T** use bright accent blue (`$vbAccentColor: #73a5ff`) as a primary CTA. It's reserved for hover states and secondary emphasis.
-- **DO** use the named font-size tokens (`$vbHeadline1FontSize`, `$vbNormalFontSize`) instead of raw rem values. The 5-step scale is the contract.
-- **DON'T** use display sizes above 24dp. freee is enterprise SaaS — restraint is the voice.
-- **DO** apply `$vbLineHeight: 1.5` universally. Japanese readers need generous vertical breathing room.
-- **DO** use the locale font stack with `-apple-system` first and Hiragino/Meiryo CJK fallbacks. The brand `freee-logo` font is for the wordmark only.
-- **DO** snap to the 4dp spacing scale (4 / 8 / 16 / 24 / 32 / 48). Never use intermediate values like 6, 10, or 14.
-- **DON'T** invent custom shadow values — use `$vbCardShadow`, `$vbFloatingShadow`, `$vbPopupShadow` for the three elevation tiers.
-- **DO** use the named z-index tokens (`$vbModalZIndex`, `$vbPopupZIndex`, etc.). The hierarchy spans 100 → 4000 with deliberate gaps.
-- **DON'T** use arbitrary z-index values like `9999` — that breaks the layered system.
-- **DO** use status colors with the matching family (e.g., `RE02` bg + `RE05/RE07` text for alerts).
-- **DON'T** mix hue families in a single status badge (e.g., never red bg with orange text).
-
-## 8. Responsive Behavior
-
-### Breakpoint
-- `$vbMobileBoundaryWidth: 48rem` (768dp) — single breakpoint between desktop and mobile
-
-### Mobile Adjustments
-- All headline sizes step down (`$vbMobileHeadline1FontSize: 16dp` vs. desktop 24dp)
-- Form controls remain at the same height tokens (mobile-friendly already at 36-48dp)
-- Container width adapts to viewport (no fixed mobile container)
-
-### Touch
-- Form controls at `36-48dp` heights = touch-friendly by default
-- Buttons inherit form-control heights
-
-### Image Behavior
-- Not tokenized in vibes — application-specific
-- Brand logo uses the `freee-logo` font for crisp scaling at any size
-
-## 9. Agent Prompt Guide
-
-### Quick Color Reference
-- Primary CTA / Link: `#285ac8` (`$vbPrimaryColor` / `$vbColorsP07`)
-- Accent (hover, secondary): `#73a5ff` (`$vbAccentColor` / `$vbColorsP04`)
-- Default text: `#323232` (`$vbBlackColor` / `$vbColorsGY07`)
-- Muted text: `#6e6b6b` (`$vbBurntColor` / `$vbColorsS09`)
-- Caption text: `#8c8989` (`$vbBaseColor3` / `$vbColorsS08`)
-- Page bg: `#ffffff` (or `#ebf3ff` for tinted bg)
-- Subtle surface: `#f0eded` (`$vbBaseColor1`)
-- Border default: `#e9e7e7` (`$vbBaseColor2`)
-- Alert: `#dc1e32` (`$vbAlertColor`)
-- Notice: `#be8c14` (`$vbNoticeColor`)
-- Success: `#00963c` (`$vbColorsGR05`)
-
-### Example Component Prompts
-- "Build a freee primary button: `36px` height (`$vbFormControlHeight`), bg `#285ac8`, white text, weight 500, padding `8px 16px`, `4px` radius. Hover: bg `#3264dc` (P06). Active: bg `#1e46aa` (P08). Disabled: bg + 12% black overlay (`$vbThinScrimColor`). Use Noto-friendly font stack with Hiragino fallbacks."
-- "Create a freee status badge: rounded `4px` corners, `8px 12px` padding, weight 500 12px text. For success: bg `#cdebd7` (GR02) + text `#006e2d` (GR07). For alert: bg `#fad2d7` (RE02) + text `#dc1e32` (RE05). For notice: bg `#fff0d2` (YE02) + text `#be8c14` (YE07). For info: bg `#dce8ff` (P02) + text `#285ac8` (P07)."
-- "Design a freee data table: column bg alternates white / `#f7f5f5` (`$vbColumnColor`). Row dividers `1px solid #e9e7e7`. Header row: weight 700 14px text `#323232`, bg `#f0eded`, sticky on scroll. Cell padding `12px 16px`. Selected row: bg `#ebf3ff` (P01)."
-- "Build a freee elevated card: white bg, `1px solid #e9e7e7` border, `4px` radius, `24px` padding. Box-shadow: `0 0 1rem rgba(0,0,0,0.1), 0 0.125rem 0.25rem rgba(0,0,0,0.2)` (`$vbCardShadow`). Heading at 24px weight 700 `#323232`. Body at 14px line-height 1.5 `#323232`."
-- "Create a freee form input: `36px` height, `1px solid #8c8989` border, `4px` radius, `12px` horizontal padding. Placeholder color `#8c8989`. Focus: border `#285ac8`, no shadow ring. Error state: border `#dc1e32`, helper text `#dc1e32` 12px below."
-
-### Iteration Guide
-1. **Always reference semantic tokens (`$vbPrimaryColor`, `$vbAlertColor`)** instead of scale values (`$vbColorsP07`, `$vbColorsRE05`) when writing component-level code.
-2. **The 9-hue palette is comprehensive** — don't introduce off-system hex values. If you need green, use the GR scale; if you need teal, use BG.
-3. **`#285ac8` is both the link color AND the primary button color** — they're the same semantic in vibes. Maintain visual coherence.
-4. **`border-radius: 4px`** is the de facto standard (vibes doesn't tokenize radius, components use 4px consistently).
-5. **Type scale: 10 / 12 / 14 / 16 / 24dp** — five steps total. Don't introduce 18 or 20 or 28.
-6. **Mobile shrinks H1 from 24dp → 16dp**, H2 from 16dp → 14dp. H3 stays at 14dp.
-7. **Spacing snaps to the 4dp scale: 4 / 8 / 16 / 24 / 32 / 48**. Never 6, 10, or 14.
-8. **Three shadow recipes only** (`$vbCardShadow`, `$vbFloatingShadow`, `$vbPopupShadow`) — graduated radius and offset.
-9. **Z-index uses named tokens** with massive gaps (100 / 200 / 500 / 700 / 1000 / 1500 / 2000 / 3000 / 4000) — leaves room for future layers.
-10. **Form-control heights are tokens** (24 / 36 / 48dp) — never use arbitrary heights for inputs/buttons.
-11. **Line-height 1.5 is universal** — preserves Japanese vertical rhythm and accessibility.
-12. **The brand wordmark uses Noto Sans CJK JP Medium** loaded as `font-family: 'freee-logo'` from Google Fonts — everywhere else uses the system stack.