DESIGN.md@web · diff
git:20260705.39f1bf7 to git:20260712.e3511ea
75 added, 63 removed. Audit A to A.
- # Design System: Flc's Skills Marketplace
+ # Design System: Technical Atlas
- ## 1. Visual Theme & Atmosphere
- The interface is a workshop ledger for agent workflows: editorial, precise, and built for scanning. It should feel like a high-quality command archive rather than a marketing page.
+ ## 1. Visual Direction
- - Density: 6/10, balanced for repeated browsing without becoming sparse.
- - Variance: 8/10, asymmetric first viewport and staggered catalog rhythm.
- - Motion: 6/10, weighty spring motion with subtle perpetual activity on active controls.
- - Creativity: 8/10, distinctive but still practical for a developer tool.
+ The marketplace is a technical atlas for reusable agent workflows. It should feel precise, spatial, and quietly cinematic: a map of operational knowledge rather than a conventional documentation site or marketing grid.
- Do not reuse the old centered hero, pastel gradient glow, sticker-label typography, rounded pill statistics, or three-equal-card marketplace grid.
+ - Default character: deep navy field, fine coordinate grid, signal nodes, and open record rows.
+ - Creativity: 7/10. Distinctive enough to be recognizable, restrained enough for repeated technical use.
+ - Density: 5/10. The first viewport stays focused; the catalog becomes denser as users browse.
+ - Avoid the previous workshop ledger language entirely: no beige paper, verdigris, register surfaces, oversized black-on-cream typography, or archival stationery motifs.
- ## 2. Color Palette & Roles
- - **Paper Clay** (#F4F1EA) - Primary page canvas.
- - **Bone Surface** (#FBFAF6) - Primary elevated surface and modal body.
- - **Register Surface** (#E8E1D4) - Secondary bands, side rails, quiet filled controls.
- - **Charcoal Register** (#1D1C19) - Primary text and structural marks. Never use pure black.
- - **Graphite Note** (#6D6961) - Secondary copy, helper text, inactive controls.
- - **Faint Rule** (rgba(29, 28, 25, 0.12)) - Hairline borders and dividers.
- - **Verdigris Mark** (#3E8F78) - The only accent. Use for primary actions, active state, focus rings, and selected metadata.
- - **Night Canvas** (#151512) - Dark theme canvas.
- - **Night Surface** (#201F1B) - Dark theme elevated surface.
- - **Night Rule** (rgba(244, 241, 234, 0.14)) - Dark theme structural lines.
+ ## 2. Color System
- Only Verdigris Mark may behave as an accent. No purple, blue neon, candy gradients, outer glow shadows, or oversaturated highlights.
+ ### Dark signal
- ## 3. Typography Rules
- - **Display:** Satoshi, Geist, or a local sans fallback. Tight tracking, controlled clamp scale, high weight only where hierarchy demands it.
- - **Body:** Satoshi, Geist, or local sans fallback. Relaxed leading and a maximum readable measure near 65 characters.
- - **Mono:** JetBrains Mono, SFMono-Regular, or ui-monospace. Use for commands, install names, dates, file counts, and compact index metadata.
- - **Banned:** Inter, generic serif fonts, browser-default control typography, exaggerated hero-scale type in compact panels.
+ - Atlas Ink: `#07101E` — page canvas.
+ - Station Surface: `#0D1B2E` — install panel, modal, and elevated controls.
+ - Deep Station: `#102238` — secondary surfaces.
+ - Primary Text: `#EEF6FF`.
+ - Muted Text: `#8FA4BA`.
+ - Coral Signal: `#FF715B` — primary accent, active nodes, important actions.
+ - Cyan Signal: `#70D7E5` — focus, navigation, and information signal.
- ## 4. Component Stylings
- - **Buttons:** Flat, tactile, minimum 44px target. Active state translates down 1px. Primary uses Verdigris Mark fill; secondary uses transparent surface with a hairline rule.
- - **Cards and records:** Use cards only for individual records, modal bodies, and command surfaces. Catalog records should feel like ledger entries with visible dividers, not floating marketing cards.
- - **Inputs:** Label or visible context above or beside the input. Focus ring uses Verdigris Mark. No floating labels.
- - **Command blocks:** Mono text, stable height, copy icon button, clear step label, selected command text.
- - **Loaders:** Skeleton blocks that match the final layout. No circular spinners.
- - **Empty states:** Quiet composed empty state with a structural mark and direct text. No generic decorative icon cluster.
- - **Error states:** Inline, close to the failed content, with plain language.
+ ### Light signal
- ## 5. Layout Principles
- - First viewport is asymmetric: editorial copy and primary command surface on one side, live index records on the other.
- - Use CSS Grid for major layout. Avoid percentage math and nested cards.
- - Multi-column layouts collapse below 768px.
- - Every element has its own clear spatial zone. No overlapping text, controls, or decorative content.
- - Catalog layout should vary scale and rhythm while keeping predictable scanning.
- - Use max-width containment around 1400px.
- - Do not create fake metrics or statistics. Counts must come from real data already in the app.
+ The light theme is the same atlas system under daylight, not a separate aesthetic.
- ## 6. Motion & Interaction
- - Use spring transitions with stiffness 100 and damping 20 for major interactions.
- - Animate only transform and opacity.
- - Use staggered cascade reveals for skill records.
- - Active controls may use a subtle repeating underline, shimmer, or small transform loop.
- - Respect reduced motion by keeping interaction readable when motion is minimized.
+ - Canvas: `#E7EEF5`.
+ - Station Surface: `#F6F9FC`.
+ - Secondary Surface: `#DCE7EF`.
+ - Primary Text: `#0B1825`.
+ - Muted Text: `#526A7E`.
+ - Coral Signal: `#E95545`.
+ - Cyan Signal: `#147F91`.
+ Never introduce purple AI gradients, beige paper surfaces, neon outer glows, or pure black.
+
+ ## 3. Typography
+
+ - Display: `Avenir Next`, Avenir, `Century Gothic`, or a humanist sans fallback. Use for the hero, section titles, modal titles, and record names.
+ - Interface: Inter or the system sans stack. Use for descriptions, controls, and navigation.
+ - Mono: SFMono-Regular, Menlo, or Consolas. Use for install commands, identifiers, counts, dates, and compact status text.
+ - Headlines are geometric and humanist, with strong weight and open counters; they must fit cleanly on a 1280px desktop and 390px mobile viewport.
+
+ ## 4. Layout
+
+ - Maximum content width: `1360px`.
+ - Header: simple brand mark, theme selector, and GitHub link.
+ - First viewport: asymmetric two-column composition. Search and collection facts sit with the main statement; the install station is the dominant secondary object.
+ - Catalog: a full-width surface band containing open horizontal records separated by signal rules. Fade the band in over 48px at the top, then keep the surface opaque through the bottom of the page so record dividers stay easy to scan without reintroducing the page grid. Do not turn it into a generic card grid.
+ - Detail: a large focused modal that preserves browsing context and uses the same station geometry.
+ - Mobile: stack the hero and install station; catalog rows reduce metadata without losing the primary action.
+
+ ## 5. Component Language
+
+ - Brand mark: a white geometric SVG `FS` monogram on a coral cut-corner tile, offset over an Atlas Ink tile to create a compact two-layer signal mark. Keep the ink layer structural rather than shadow-like.
+ - Signal nodes: small diamonds or points, used sparingly for catalog position and spatial rhythm.
+ - Install station: one elevated panel with a coral top rule and exact copy controls.
+ - Search: one long command-like field with a cyan icon zone and keyboard shortcut.
+ - Catalog rows: open, border-separated, and hover toward a faint coral signal wash.
+ - Buttons: square or lightly rectangular, minimum 44px target, thin structural border, no pill treatment unless required by an external component.
+ - Empty/error states: inline atlas messages near the affected content.
+
+ ## 6. Motion
+
+ - Use 160–220ms state transitions and restrained spring entrances.
+ - Animate opacity and transform for catalog filtering and modal transitions.
+ - Hover states may illuminate a signal node or move an arrow by a few pixels.
+ - Respect `prefers-reduced-motion` everywhere.
+
## 7. Functional Invariants
+
- Keep generated skill data flow unchanged.
- Keep search by display name and description.
+ - Keep newest-first ordering.
- Keep URL query behavior with `?skill=<slug>`.
- Keep modal fetch through `/api/skills/[slug]`.
- Keep repository install copy behavior and individual skill install copy behavior.
- Keep GitHub source links and relative Markdown link resolution.
- Keep theme switching with `system`, `light`, and `dark`.
- - Keep Google Analytics event names and payload intent.
- - Keep responsive mobile behavior without horizontal overflow.
+ - Keep all existing Google Analytics event names and payload intent.
+ - Keep loading, empty, and invalid-slug states.
+ - Keep responsive behavior without horizontal overflow.
- ## 8. Anti-Patterns (Banned)
- - No emojis anywhere.
- - No Inter.
- - No pure black (#000000).
- - No neon glows or outer glow shadows.
- - No purple/blue AI gradients.
- - No centered hero for the first viewport.
- - No three-column equal feature rows as the defining marketplace pattern.
- - No fake numbers, fake performance metrics, or fabricated proof points.
- - No `LABEL // YEAR` typography.
- - No AI copywriting cliches such as "Elevate", "Seamless", "Unleash", or "Next-Gen".
- - No scroll prompts, bouncing arrows, or filler helper text.
- - No custom mouse cursors.
- - No broken remote image dependencies.
+ ## 8. Anti-patterns
+
+ - No reuse of the previous ledger/workshop visual language.
+ - No beige, paper clay, verdigris, or stationery metaphors.
+ - No default bento grid or repeated floating cards.
+ - No fake metrics or fabricated proof.
+ - No decorative badge clutter or hero eyebrow labels.
+ - No generic AI gradients or glow-heavy cyberpunk treatment.
+ - No text glyphs when an existing icon component communicates the action.
+ - No clipped commands, headings, or mobile controls.