# Sentinel · Archetype Spec Sheet · v1.0 **Status:** authored from v1 Ch10 + Finding 12 mock + design-system-spec parity audit. Source of truth for the enterprise / product archetype. **Use:** two-paste workflow per prompt. 1. Paste [governance.spec.md](governance.spec.md) first (universal gates — non-negotiable). 2. Paste the fenced block below second (Sentinel-specific rules). Consumed by Prompt 1 (token generation), Prompt 03 (foundation components), Prompt 04 (composite components), Prompt 05 (UI patterns), Prompt 08 (spec page), Prompt 09 (page layout assembly). **Origin:** [reference/book-v1.html](../../reference/book-v1.html) Ch10 lines 2704–2899. Mock pattern: [finalbookplan.md](../../finalbookplan.md) Finding 12. Coverage parity: [reference/design-system-spec-v1.html](../../reference/design-system-spec-v1.html) — that page is itself a Sentinel example. --- ``` ═══════════════════════════════════════════════════════════════ SENTINEL · ARCHETYPE SPEC · v1.0 Enterprise / Product systems ═══════════════════════════════════════════════════════════════ TAGLINE: an enterprise-grade design system for monitoring tools, dashboards, and data-dense products. Clear, helpful, respectful of expertise. PREREQUISITE: governance.spec.md MUST be loaded before this spec. Sentinel inherits all universal gates and adds the overrides at the end of this block. ─────────────────────────────────────────────────────────────── THEME ─────────────────────────────────────────────────────────────── Mode: LIGHT-FIRST; dark mode is a parallel theme via [data-theme="dark"] override (must be defined even if unshipped — governance requirement) Palette character: warm-neutral grays + saturated semantic ramps. NEVER pure #000 or pure #FFF for text/bg pairings. Reason: enterprise products run for 8+ hour sessions in office lighting. Light mode is the default expectation; high-contrast neutrals reduce eye fatigue at task focus. ─────────────────────────────────────────────────────────────── TOKEN NAMING — TWO-LAYER ARCHITECTURE ─────────────────────────────────────────────────────────────── Strategy: PRIMITIVE RAMPS (Layer 1) + SEMANTIC ALIASES (Layer 2) Components NEVER reference Layer 1 directly — only Layer 2. Layer 1 (primitives — the raw palette): --color-primary-50…900 navy ramp (700 = anchor) --color-accent-50…900 orange ramp (500 = CTA anchor) --color-link-50…900 link teal/blue ramp --color-success-50…900 --color-warning-50…900 --color-error-50…900 --color-neutral-50…900 warm gray ramp (workhorse) Layer 2 (semantic — what components consume): --text-primary, --text-secondary, --text-tertiary, --text-disabled, --text-inverse, --text-link --surface-page, --surface-card, --surface-sunken, --surface-sidebar, --surface-header, --surface-subheader --border-subtle, --border-default, --border-strong, --border-focus Reason: enterprise products need 9-step granularity for status badges, charts, table tints, hover/active states, severity levels. Naming roles AND steps lets the AI compose precisely ("text on success-tinted row" → text-primary on success-50). ─────────────────────────────────────────────────────────────── COLOR TOKENS (canonical defaults — substitute equivalents) ─────────────────────────────────────────────────────────────── ▼ LAYER 1 — PRIMITIVE RAMPS Primary navy (700 = anchor): --color-primary-50 #F0F2F7 --color-primary-100 #DAE0EC --color-primary-200 #B0BDD5 --color-primary-300 #8599BC --color-primary-400 #5B76A0 --color-primary-500 #3D5A80 --color-primary-600 #28406A --color-primary-700 #1B2A4A /* anchor */ --color-primary-800 #131F38 --color-primary-900 #0A1428 Accent orange (500 = CTA anchor): --color-accent-50 #FFF4E5 --color-accent-100 #FFE0B3 --color-accent-300 #FFB84D --color-accent-500 #FF9900 /* CTA anchor */ --color-accent-700 #CC6A00 --color-accent-900 #7A3D00 Link (separate from primary — never reuse navy for links): --color-link-500 #0066CC Semantic ramps (each 50/100/300/500/700/900 minimum): --color-success-500 #00A878 --color-success-700 #045545 --color-warning-500 #D97706 --color-warning-700 #92400E --color-error-500 #DC3545 --color-error-700 #B12704 Neutral warm gray (workhorse): --color-neutral-50 #FAFAF9 --color-neutral-100 #F5F5F4 --color-neutral-200 #E7E5E4 --color-neutral-300 #D6D3D1 --color-neutral-400 #A8A29E --color-neutral-500 #78716C --color-neutral-600 #57534E --color-neutral-700 #44403C --color-neutral-800 #292524 --color-neutral-900 #1C1917 ▼ LAYER 2 — SEMANTIC ALIASES Text: --text-primary var(--color-neutral-900) --text-secondary var(--color-neutral-700) --text-tertiary var(--color-neutral-500) --text-disabled var(--color-neutral-300) --text-inverse var(--color-neutral-50) --text-link var(--color-link-500) Surfaces: --surface-page var(--color-neutral-50) --surface-card #FFFFFF --surface-sunken var(--color-neutral-100) --surface-sidebar var(--color-primary-700) --surface-header var(--color-primary-900) --surface-subheader var(--color-primary-500) Borders: --border-subtle var(--color-neutral-100) --border-default var(--color-neutral-300) --border-strong var(--color-neutral-500) --border-focus var(--color-accent-500) Focus ring (governance requirement): --color-focus-ring rgba(255,153,0,0.4) accent at 40% ▼ DOMAIN EXTENSIONS (extend per product) Severity (monitoring/alerting/critique products): --severity-critical var(--color-error-500) --severity-high #EA580C --severity-medium var(--color-warning-500) --severity-low #84CC16 --severity-info var(--color-link-500) Annotation pins (review/critique products): --annotation-pin-1 var(--severity-critical) --annotation-pin-2 var(--severity-high) --annotation-pin-3 var(--severity-medium) Reason: domain extensions ALWAYS reference Layer 2 or Layer 1 primitives — never raw hex. New product domains add their own semantic ramp (e.g., --priority-* for project tools). ─────────────────────────────────────────────────────────────── THE ACCENT-CTA RULE (Sentinel keystone) ─────────────────────────────────────────────────────────────── Orange #FF9900 on white = 2.30:1 = WCAG FAIL. Orange #FF9900 + dark text (#1C1917) = 7.0:1 = AAA. THE RULE: --color-accent-500 is a BACKGROUND color ONLY. NEVER a text color on light surface. Primary CTA = orange-bg + dark-text. Banned: white-text-on-orange anywhere. ─────────────────────────────────────────────────────────────── TYPOGRAPHY ─────────────────────────────────────────────────────────────── Approach: FIXED px MODULAR scale — NEVER fluid clamp Ratio: 1.125 (major second) Base: 14px (--text-body) Family: SANS ONLY — Inter (fallback: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif) Display family: same as body (NO serif display) Scale (12 steps, fixed px): --text-h1 34px page title --text-h2 30px major section --text-h3 26px subsection --text-h4 22px card title, dialog title --text-h5 20px sidebar headers --text-h6 18px inline group headers --text-body-lg 16px hero paragraphs, marketing pages --text-body 14px DEFAULT — UI, forms, tables --text-body-sm 13px dense UI, table cells, helper text --text-caption 12px metadata, timestamps, file sizes --text-overline 12px section labels (small caps + tracking) --text-code 13px monospace (JetBrains Mono, Menlo) Font weights: --weight-regular 400 body, descriptions --weight-medium 500 labels, navigation --weight-semibold 600 headings, emphasized data --weight-bold 700 page titles, table headers Line heights: --leading-tight 1.20 h1/h2 (display) --leading-snug 1.30 h3/h4 --leading-normal 1.50 body, table rows --leading-relaxed 1.60 body-lg, prose paragraphs Letter spacing: --tracking-tight -0.01em h1/h2 --tracking-normal 0 body --tracking-wide 0.06em overline (small caps) Special: font-feature-settings: "tnum" 1, "lnum" 1 tabular nums in data tables Reason: dashboards and tables need pixel-perfect alignment; serif decoration competes with information density. Modular ratio keeps the scale predictable. Tabular numerals are non-negotiable for any column of numbers. H1 tops out at 34px — Sentinel never goes hero-large (that's Harbor's territory). Wasting screen real estate on oversized titles starves the data. ─────────────────────────────────────────────────────────────── DENSITY ─────────────────────────────────────────────────────────────── Character: COMPACT — task-oriented, information-dense Spacing scale (4px base, 12-step): --space-25 2px tight icon-text pair --space-50 4px inline gap --space-75 6px badge inner padding --space-100 8px DEFAULT gap --space-150 12px form field internal --space-200 16px card padding, between fields --space-300 24px between sections within page --space-400 32px between major page sections --space-500 40px page top spacing --space-600 48px rare — major breakpoint --space-800 64px page header/sidebar offset --space-1000 80px full-page hero (rare in product UI) Section padding: --space-300 (24px) standard, --space-200 (16px) in dense table contexts Page padding: --space-400 (32px) horizontal on desktop Content widths: --content-narrow 480px form modals, settings panels --content-default 720px read-focused panels --content-wide 1024px full content area --content-full none dashboards, tables — fill viewport Reason: product UI is task-oriented; whitespace costs density. A user staring at this for 8 hours wants the data, not the poetry. Compact spacing maximizes information per screen without crowding. ─────────────────────────────────────────────────────────────── ACCENT STRATEGY ─────────────────────────────────────────────────────────────── Strategy: MULTI-RAMP + SEMANTIC Required ramps (50–900 each): - Primary (navy or brand) - Accent (CTA color — must respect accent-CTA rule) - Link (distinct from primary) - Success / Warning / Error - Neutral (warm gray workhorse) Optional ramps (per product domain): - Severity (critical/high/medium/low/info) - Priority (P0/P1/P2/P3) - Status (active/pending/blocked/completed) - Charts (categorical 8-color palette + sequential ramp) Banned: pastel-only palettes, single-hue accent (that's Harbor), gradient backgrounds, indigo/purple in any ramp (cliched "AI startup" signal) Reason: enterprise products encode meaning in color (severity, status, badges, table tints, charts). 9-step granularity gives precise hover/active/selected states without guessing. Semantic ramps mean a critical alert is always "--color-error-500", not "the red one". ─────────────────────────────────────────────────────────────── ELEVATION ─────────────────────────────────────────────────────────────── Default: FLAT WITH HAIRLINE BORDERS — surfaces use 1px --border-default, no shadow Shadows: reserved for FLOATING elements only (popovers, dropdowns, dialogs, toasts) Shadow color: cold neutral (rgba black) — Sentinel does NOT use warm oklch shadows (that's Harbor) --shadow-0 none + 1px border card default --shadow-1 0 1px 2px rgba(0,0,0,0.05) card:hover --shadow-2 0 2px 4px rgba(0,0,0,0.08) dropdown --shadow-4 0 4px 8px rgba(0,0,0,0.10) tooltip, menu --shadow-8 0 8px 16px rgba(0,0,0,0.12) dialog, modal --shadow-16 0 16px 32px rgba(0,0,0,0.16) drag preview Banned: warm oklch shadows (that's Harbor — wrong archetype) Banned: strong border + strong shadow on the same element Banned: shadows on default surfaces (cards, panels) — flat with border instead Reason: borders communicate structure precisely without the visual weight of shadows. Shadows reserved for float = a shadow always means "this is above the page". Predictable. ─────────────────────────────────────────────────────────────── RADII ─────────────────────────────────────────────────────────────── Scale (8 steps — wider range than Harbor for component variety): --radius-none 0 table cells, sticky headers --radius-xs 2px badges, severity pills (small) --radius-sm 4px DEFAULT — cards, alerts, inputs --radius-md 6px buttons, switches --radius-lg 8px primary buttons (Amazon-style) --radius-xl 12px dialogs, drawers --radius-pill 9999px chips, removable filters --radius-circle 50% avatars, annotation pins Banned: super-rounded everything (>16px on cards), pill-rounded buttons (too playful for enterprise — that's Current) ─────────────────────────────────────────────────────────────── MOTION ─────────────────────────────────────────────────────────────── --duration-shortest 100ms hover color, icon swap --duration-short 150ms DEFAULT — buttons, dropdowns, toggles --duration-standard 200ms dialog open/close, drawer slide --duration-long 300ms page transitions, major state --easing-standard cubic-bezier(0.4, 0, 0.2, 1) default --easing-enter cubic-bezier(0, 0, 0.2, 1) decelerate --easing-exit cubic-bezier(0.4, 0, 1, 1) accelerate Use motion functionally: state change, position change, visibility change. NEVER decorative. Reduced-motion fallback: fade-only, --duration-shortest. Banned: bouncing animations (overshoot easing on UI), flourish animations on data, parallax, scroll-jacking, animated gradient backgrounds, marquee, rotating headlines. Reason: minimal, functional. 150ms says "the system responded"; anything longer says "the system thinks slowly". ─────────────────────────────────────────────────────────────── ICONOGRAPHY ─────────────────────────────────────────────────────────────── Family default: LUCIDE Reason: Lucide is the modern enterprise / SaaS convention — Tailwind, Vercel, Linear, Notion, Supabase, modern dashboards converge on it. Neutral, functional, instantly recognizable to the user base. 2px stroke matches Sentinel's compact density without feeling fragile. Substitute Material Symbols (Google's enterprise default) if Lucide unavailable. NEVER use Phosphor (too editorial, breaks tone) or Tabler (too monospace-tool, that's Lattice). Grid: 24px standard; 16px allowed for dense table / inline UI; 20px for buttons Stroke: 2px, rounded line caps and joins Color: inherit via currentColor (NEVER hex) Style: line icons by default; FILLED variants allowed for severity badges, status indicators (where fill encodes meaning — critical = filled triangle, info = filled circle) Icon weight matching: 16px uses 1.5px stroke; 24px uses 2px stroke; never mix stroke widths in one icon group Banned: ✗ Emoji as icon ✗ Multi-color illustrations as UI icons (illustrations OK in empty states) ✗ Gradient circle backgrounds behind icons ✗ Mixing icon families on the same surface ✗ Animated icons (except spinners and progress) ─────────────────────────────────────────────────────────────── APPLICATION LAYOUTS — page composition vocabulary (use ONLY these — no marketing-style section templates) ─────────────────────────────────────────────────────────────── L1 PAGE SHELL — App Frame Structure: header (top, --surface-header navy) + sidebar (left, --surface-sidebar) + main content area (--surface-page, scrolls independently) + optional sub-header Use for: every authenticated app page (the chrome) Banned: floating chrome, transparent header over content, hamburger-only nav on desktop L2 SIDEBAR LAYOUT — List + Detail Structure: navigation sidebar + secondary list pane (320– 400px) + main detail pane (rest of viewport) Use for: inbox, file browser, settings with categories, search results Banned: collapsing both panels at once on tablet (becomes unusable) L3 FULL-WIDTH DASHBOARD Structure: header + dashboard widgets in 12-col responsive grid (cards, charts, tables) Use for: monitoring, analytics, overview pages Widget grid: --space-300 (24px) gutters, cards --radius-sm + --shadow-0 (flat with border) Banned: hero metric numbers > 48px (data should be readable in scanning, not impressive) L4 SPLIT PANEL Structure: 60/40 or 50/50 vertical split with resizable divider Use for: code editor + preview, table + detail, comparison views Required: resize handle, keyboard-resizable (Shift+Arrow), persistence of pane width per user L5 FOCUS MODE — Form / Wizard Structure: centered single-column, --content-narrow or --content-default, sticky header with progress, sticky footer with primary action Use for: multi-step forms, onboarding, checkout flows Banned: multi-column forms, in-page tabs that cause progress loss L6 EMPTY APP STATE — First Run Structure: same shell, main content replaced with centered empty state (icon + title + body + CTA) Use for: first-time experience, zero-data states Required: clear next action, one primary CTA Composition rule: every product page is one of these six layouts. The AI assembles into a layout, never invents new chrome. ─────────────────────────────────────────────────────────────── COMPONENT LIBRARY — generate in this priority order ─────────────────────────────────────────────────────────────── ▼ FOUNDATION (Layer 1 — Prompt 03) 1. Button Variants: primary (orange bg, dark text — accent-CTA rule) / secondary (outline, neutral) / tertiary (text-only) / destructive (red) Sizes: sm (h:32px) / md (h:40px) / lg (h:48px) States: default / hover / focus-visible / active / disabled / loading Radius: --radius-lg (8px) — Amazon-button feel Sentinel rule: max ONE primary per local action group (modal footer, toolbar) Sentinel rule: destructive button uses --color-error-500 bg + white text (passes contrast) 2. Icon button Sizes: sm (28px) / md (36px) / lg (44px) Required: aria-label, tooltip on hover/focus Sentinel rule: ghost background by default; outline on dense toolbars where action discoverability matters 3. Field (text / textarea / select / search) Variants: default / with-icon-leading / with-icon-trailing / textarea / select States: empty / filled / focus / error / disabled / read-only Required: label[for] above (NEVER floating), helper text below input, error text REPLACES helper text Required field: parenthetical "(required)" inline (NOT just asterisk) Sentinel rule: focus ring 3px --color-focus-ring around the input wrapper BANNED: floating labels, placeholder-as-label, asterisk- only required indicator 4. Selection controls Checkbox — square 16px, --radius-xs, check icon on fill, indeterminate state required Radio — circle 16px, dot on fill Switch — track 36×20px, thumb 16px circle, slide animation States: unchecked / checked / indeterminate (checkbox only) / disabled / focus-visible Sentinel rule: switches for binary settings, checkboxes for multi-select, radios for one-of-many 5. Tag / Badge Shape: --radius-xs (rectangular) — Sentinel uses square badges (chips are pill-shaped) Variants: neutral / success / warning / error / info / accent / count (numeric) Sizes: sm (h:18px) / md (h:22px) Sentinel rule: count badges never go above "99+" 6. Chip Shape: --radius-pill (9999px) Variants: static (filter pill) / removable (with × button) / selectable (with check on selected) / icon-leading Sentinel rule: chips for filters and metadata; never use for primary actions 7. Avatar Sizes: sm (24px) / md (32px) / lg (48px) / xl (96px) Variants: photo / initials / icon-fallback Sentinel rule: photo allowed (real users in enterprise); initials when no photo; never stock images ▼ COMPOSITE (Layer 2 — Prompt 04) 8. Card variants 8a. Card — Flat (default — workhorse) 1px --border-default, no shadow, --surface-card bg Use for: 90% of cards (settings panels, list items, widget containers) 8b. Card — Raised No border, --shadow-1, --surface-card bg Use for: cards floating above sunken backgrounds 8c. Card — Interactive Flat + hover (background → --surface-sunken, cursor: pointer) Use for: clickable card grids 8d. Card — Selected Flat + 2px left-border --color-accent-500 Use for: selected row in list, active item in grid 9. Alert (in-page persistent message) Structure: left-border accent (4px, semantic color) + icon (24px, semantic) + title + body + optional action link + optional dismiss × Variants: info / success / warning / error Required: aria-live appropriate to severity Sentinel rule: alert text uses --text-primary; semantic color is the LEFT BORDER and ICON, not the background fill (preserves contrast) 10. Toast (transient notification) Position: bottom-right (desktop) / bottom-center (mobile) Structure: icon + message + dismiss × button Variants: neutral / success / error Auto-dismiss: 5s default; persistent for errors Animation: fade + slide-up 8px, --duration-standard Sentinel rule: max 3 toasts stacked; older toasts fade 11. Tooltip Trigger: hover (delay 400ms) + focus Position: above default; flip if viewport edge Style: --color-neutral-900 bg, white text, --text-caption, max-width 240px, --shadow-4 Required: aria-describedby Sentinel rule: tooltips for icon-button labels and keyboard shortcuts; never for critical info 12. Dialog (modal) Structure: title (h4, --weight-semibold) + close × + body + footer (buttons right-aligned) Footer order: secondary "Cancel" left, primary action right; destructive replaces primary if applicable Backdrop: rgba(0,0,0,0.5) Width: --content-narrow default; --content-default for forms Required: focus trap, Esc to close, return focus to trigger Animation: fade backdrop + scale-up dialog (0.96 → 1.0), --duration-standard 13. Drawer (slide-in panel) Edge: right by default (cart, comments, settings, details); left for navigation flyouts Width: 400px desktop / full-width mobile Backdrop: same as dialog OR none for non-modal drawers Required: Esc to close, focus trap (modal only) Sentinel rule: drawers for in-context detail views; dialogs for confirmations and short forms 14. Tabs Style: underline on active (3px --color-accent-500), no background fill Variants: line (default) / pills (compact toolbars only) Navigation: ArrowLeft/Right cycles, Home/End for first/last Required: roving tabindex, aria-selected, aria-controls Sentinel rule: tabs for sibling content; never for navigation between unrelated pages Sentinel rule: badge counts allowed inline ("All issues 12") 15. Loading states 15a. Spinner — circle, 24px default, --color-accent-500 stroke, 1s rotation, --easing-standard 15b. Progress bar — 4px height, determinate (% width animated) or indeterminate (sliding gradient over neutral track) 15c. Skeleton — opacity-pulse 1s on neutral block, NO gradient shimmer (Sentinel keeps it boring) Sentinel rule: skeleton MUST match the shape of the content it replaces (not generic rectangles) Sentinel rule: text label required next to spinner for any wait > 1s ("Analyzing… 68%") 16. Dropdown / Select (popover-based) Trigger: button-like, chevron-down icon trailing Menu: --shadow-4, --radius-sm, --space-50 (4px) inner item padding Item: hover --surface-sunken, selected check icon trailing Required: ArrowUp/Down to navigate, Enter to select, Esc to close, type-ahead search Sentinel rule: combobox if list >7 items (add filter input) 17. Date picker Style: calendar grid, single date / range / time variants Required: keyboard navigation (Arrows + PageUp/Down for months), aria-label per cell, today indicator Sentinel rule: use native input[type=date] on mobile; custom popover on desktop 18. Command palette (Cmd+K) Structure: full-screen overlay or centered modal, search input + result list grouped by section + keyboard hints in footer Required: focus on open, Esc to close, Cmd+K to toggle, ArrowUp/Down to navigate, Enter to execute Sentinel rule: command palette is the power-user accelerator — must include actions reachable via the UI, not a separate feature set 19. Code block Style: monospace --text-code, --surface-sunken bg, --radius-sm, --space-200 padding, optional copy button Variants: inline (code tag) / block (pre>code) / with line numbers / with diff highlighting Sentinel rule: dark theme variant required (devs paste into Slack/docs) ▼ PATTERNS (Layer 3 — Prompt 05) 20. Data table (THE iconic Sentinel component) Structure: sticky header, hoverable rows, selectable rows, selected row left-border accent, sortable columns (chevron icons), action menu per row (kebab icon), sticky pagination footer Cell density: --space-150 (12px) vertical padding Number columns: tabular numerals, right-aligned Status columns: badges (--text-caption) Bulk actions: header morphs into action bar when rows selected (count + Delete + Archive + Export) Required: column resize, column reorder (drag), column show/hide, persistent user preferences Empty state: in-table empty message (NOT replacing the chrome) Banned: zebra-striped rows (use hover instead — striping adds visual noise without information) 21. Form layout Layout: single-column, --content-narrow or --content-default, labels above inputs Spacing: --space-200 (16px) between fields, --space-300 (24px) between groups Required fields: parenthetical "(required)" inline Submit row: --border-subtle divider above, buttons right- aligned, primary right Inline validation: on blur (not on every keystroke) Sentinel rule: NO multi-column forms unless paired fields ("First name / Last name") on desktop 22. Empty state Structure: 64px circle icon (--surface-sunken bg) + h4 heading + 1–2 sentence body + primary CTA Tone: helpful, not apologetic — "No critiques yet — upload a screenshot to start" Sentinel rule: empty state always offers an action (CTA), never a dead end 23. Search + filter pattern Structure: search input (with icon-leading) + filter chips (removable) + sort dropdown — all in one row above the data Required: Cmd+F focuses search, Esc clears, filter chip count visible Sentinel rule: applied filters always visible as chips (NEVER hidden behind a "Filters (3)" button alone) 24. Wizard / Stepper Structure: top progress (numbered steps with connectors), main content area (one step at a time), sticky footer (Back left, Next right, primary always last step) Required: keyboard navigation, ability to jump back to completed steps Sentinel rule: max 5 steps before splitting flow into shorter wizards 25. Detail header (entity page) Structure: breadcrumb + entity title + status badge + metadata row (created/owner/etc) + action buttons (right-aligned) Sentinel rule: page title size --text-h2 (NEVER h1 — h1 reserved for page-shell title) ▼ DOMAIN LAYER (Layer 4 — product-specific composites) Examples (each composes Layer 1–3 with Sentinel rules): 26. Severity badge Variants: critical / high / medium / low / info Style: filled icon + label, --radius-xs, --text-caption Required: icon + text both (color alone fails colorblind a11y) 27. Annotation pin (numbered marker on screenshot/canvas) Style: --radius-circle, severity-colored, white number, --text-body-sm bold, --shadow-2 for depth Required: aria-label "Issue {number}: {title}" 28. Critique card (review/audit products) Structure: left-border (4px, severity color) + head (severity badge + chips + ID #) + h4 title + body explanation + suggested fix block (--surface-sunken bg, --space-150 padding) 29. Dropzone Structure: dashed border, icon (48px, thin stroke), heading, constraints line (file types, max size) States: idle / drag-over (--surface-sunken bg) / uploading (progress) / success / error Required: file input as fallback, keyboard-accessible "browse" button 30. Charts Palette: 8-color categorical (no gradient between), sequential ramp for heat (use neutral-100 → primary-500) Required: legend, tooltips on hover, keyboard navigation, color + pattern (cross-hatch) for colorblind a11y Banned: 3D charts, pie charts > 6 slices, donut with center label that obscures data ─────────────────────────────────────────────────────────────── KEYBOARD-FIRST INTERACTION ─────────────────────────────────────────────────────────────── Sentinel users spend hours per day in the product. Keyboard fluency is a productivity multiplier. Every action should be reachable via keyboard, with a documented shortcut for power users. (Less aggressive than Lattice's terminal-grade keyboard-first doctrine, but more rigorous than Harbor / Current / Meridian. Mouse remains a first-class input — Sentinel doesn't push operators to memorize keys to function.) Standard shortcuts (reserve these — products inherit): ⌘K / Ctrl+K command palette (universal accelerator) ⌘/ / Ctrl+/ keyboard shortcut help overlay ⌘F / Ctrl+F focus search input ⌘↵ / Ctrl+Enter submit / commit (in dialogs, forms) Esc close dialog / drawer / popover; clear focus Tab / Shift+Tab navigate forward / back ↑↓ ←→ navigate within tabs, radio groups, menus, data-table rows, dropdowns Home / End first / last item in lists, table cells Space activate buttons, toggle switches Enter activate links, primary action in dialogs Required: ✓ Focus rings visible on all keyboard-reachable elements (3px --color-focus-ring outline, 2px offset) ✓ Tab order matches DOM / visual order (no tabindex tricks) ✓ Focus trap inside modals + drawers; Esc returns focus to trigger ✓ Keyboard shortcut help overlay accessible via ⌘/ or "?" ✓ Icon-only buttons show shortcut in tooltip on hover/focus (e.g., "Refresh — R") Sentinel rule: command palette (⌘K) MUST include every action reachable via the UI — it's the keyboard equivalent of the menu bar, not a separate feature set. Sentinel rule: data tables support row navigation via ↑↓ ←→, Enter to open, Space to select, Shift+↑↓ to extend selection, ⌘A to select all, ⌘C to copy. Sentinel rule: form fields advance with Tab; Shift+Tab back; ⌘↵ submits from any field. Banned (these break keyboard-first): ✗ Custom focus styling that hides the focus ring ✗ Click-only interactions (drag-and-drop without keyboard alternative) ✗ Modal triggers that don't accept keyboard activation ✗ Hover-only menus (must also open on focus + Enter) ─────────────────────────────────────────────────────────────── VOICE RULES — apply to ALL generated copy ─────────────────────────────────────────────────────────────── (Inherits governance Voice rules. Sentinel adds:) Three pillars: CLEAR, HELPFUL, RESPECTFUL OF EXPERTISE. • Sentence case EVERYWHERE. No Title Case, no ALL-CAPS (overline/eyebrow exception). • Verb-first CTAs. Use: "Save changes", "Run critique", "Delete report", "Create account" Banned: "Click here to save", "Submission of changes", "Account creation" • No emoji in UI — ever. • Required field indicator: parenthetical "(required)" inline. NEVER asterisk-only. • Respect reader's expertise — don't over-explain technical terms. Bad: "We checked if your colors are accessible (that means easy to see for everyone!)." Good: "Contrast ratio 3.1:1 — fails WCAG AA for body text." • Errors follow What/Why/How (governance rule, repeated for emphasis): What: [what happened] Why: [why it failed] How: [recovery action] Example: "Password must be at least 8 characters. Shorter passwords are easily cracked. Add 3 more characters." • No marketing fluff in product UI. Banned: "Let's embark on…", "Welcome to your journey…", "Unlock the power of…", "Revolutionize…" VOICE — Do / Don't pairs: Do → "Upload a screenshot to get started." Don't → "Let's embark on your design journey!" Why: marketing fluff in product UI. Do → "Contrast ratio 3.1:1 — fails WCAG AA for body text." Don't → "Your colors might not be accessible (that's bad!)" Why: respect reader's expertise. Do → "Upload failed. The file is over 10 MB. Try compressing it." Don't → "Error: Invalid file." Why: What/Why/How — give recovery, not just failure. Do → "Save changes" / "Delete report" Don't → "Submit" / "Apply" / "OK" Why: verb + object > vague verb alone. ─────────────────────────────────────────────────────────────── BANNED PATTERNS — the Sentinel anti-pattern catalog ─────────────────────────────────────────────────────────────── ▼ Token-level antipatterns ✗ Single-hue accent strategy Why: archetype mismatch — that's Harbor Use: multi-ramp + semantic ramps (50–900 each) ✗ Components reading Layer 1 primitives directly Why: breaks two-layer architecture; tight coupling Use: components ONLY consume Layer 2 semantic aliases ✗ Warm oklch shadows Why: that's Harbor — Sentinel uses cold neutral shadows Use: rgba(0,0,0,*) for shadow color ✗ Fluid clamp() typography Why: dashboards need pixel-perfect alignment Use: fixed px modular scale ✗ Serif typography Why: serif decoration competes with information density Use: sans-only (Inter) ✗ Indigo / purple in any ramp Why: cliched "AI startup" signal; not a Sentinel color Use: navy primary, orange accent, or product-specific brand ✗ Pastel-only palette Why: insufficient contrast for status/severity differentiation Use: saturated semantic ramps with verified contrast ▼ Component-level antipatterns ✗ White text on --color-accent-500 (orange) Why: 2.30:1 — WCAG FAIL Use: dark text on orange (7.0:1 AAA) — accent-CTA rule ✗ Floating labels (placeholder-as-label) Why: hides labels; fails autofill; a11y fail Use: labels above, "(required)" inline ✗ Asterisk-only required indicator Why: not screen-reader friendly without aria-required Use: parenthetical "(required)" inline + aria ✗ Zebra-striped table rows Why: visual noise without information; old-pattern Use: hover state + subtle row dividers ✗ Auto-advancing carousels in product UI Why: dashboards demand user pace Use: tabs, pagination, or static layout ✗ Hero metric numbers > 48px in dashboards Why: starves data; impressive but unscannable Use: --text-h1 (34px) maximum ✗ Multi-column forms on standard fields Why: forces zigzag scanning; fails progressive disclosure Use: single-column except paired fields (First/Last name) ✗ Modal stacking (modals opening modals) Why: focus management nightmare; user disorientation Use: drawer-from-modal or wizard within single modal ✗ Color-only encoding (severity as color alone) Why: colorblind a11y fail Use: color + icon + text label ✗ Loading spinner with no text after 1s Why: ambiguous — is it stuck, or working? Use: text label + progress % ✗ "Get Started" / "Submit" / "OK" generic CTAs Why: zero specificity Use: verb + object ("Run critique", "Save changes") ▼ Copy / voice antipatterns ✗ Marketing fluff in product UI Why: product UI is not a landing page; user is doing work Use: direct, action-oriented, specific ✗ Condescending explanations of basic terms Why: insults the reader's expertise Use: trust the reader; link to docs for definitions ✗ Title Case On Buttons Why: dated; inconsistent with sentence-case rule Use: sentence case ✗ "Oops! Something went wrong." Why: meaningless; no recovery information Use: What/Why/How — be specific ✗ Emoji in UI (success ✅, warning ⚠️, error ❌) Why: inconsistent rendering; unprofessional in enterprise Use: SVG icons with currentColor ✗ Exclamation marks in product UI Why: tonal mismatch with task-focused UX Use: declarative statements ("Saved." not "Saved!") ▼ Composition antipatterns ✗ Floating chrome (transparent header over content) Why: scrollable content collides with nav Use: solid --surface-header that stays anchored ✗ Hamburger-only nav on desktop Why: hides navigation that has the room to be visible Use: persistent sidebar (--surface-sidebar) ✗ Sticky promotional banners Why: enterprise users notice them once and resent them forever Use: in-app notification panel or release notes drawer ✗ Hero-large page titles in product UI Why: looks like marketing; wastes data real estate Use: --text-h2 max for page titles ✗ Empty state without action Why: dead end — user doesn't know what to do Use: every empty state offers a CTA ✗ Required filters that hide all data Why: zero-state on first load is confusing Use: sensible default filter (e.g., last 7 days) on entry ✗ Modal forms with > 8 fields Why: cognitive overload; modal context insufficient Use: dedicated page (Focus Mode layout L5) instead ─────────────────────────────────────────────────────────────── BYOC — REQUIRED COLOR ROLES (Bring Your Own Colors) ─────────────────────────────────────────────────────────────── If you're using Prompt 1b (BYOC variant) instead of Sentinel's canonical navy + orange palette, your supplied palette MUST cover these RAMPS at minimum. Sentinel's two-layer architecture requires Layer 1 PRIMITIVE RAMPS (50–900 step granularity) so that Layer 2 SEMANTIC ALIASES can bind precisely. Required Layer 1 ramps (7 ramps × ~9 steps = ~63 colors): 1 Primary 50/100/200/300/400/500/600/700/800/900 (anchor at 700 typically — sidebar/header) 2 Accent 50/100/300/500/700/900 (CTA color — must respect Accent-CTA rule: 500-step is bg-only, NEVER text on light bg) 3 Link 500 minimum (distinct from primary navy — never reuse navy for links; use blue/teal) 4 Success 50/100/300/500/700 minimum 5 Warning 50/100/300/500/700 minimum 6 Error 50/100/300/500/700 minimum 7 Neutral 50/100/200/300/400/500/600/700/800/900 (warm gray workhorse — used for text / surfaces / borders via Layer 2 aliases) Required Layer 2 aliases (auto-derived from Layer 1): text-primary / text-secondary / text-tertiary / text-disabled / text-inverse / text-link surface-page / surface-card / surface-sunken / surface-sidebar / surface-header / surface-subheader border-subtle / border-default / border-strong / border-focus color-focus-ring (accent at 40% opacity) Optional (per product domain — extend as needed): + Severity (critical/high/medium/low/info) — for monitoring + Priority (P0/P1/P2/P3) — for project tools + Status (active/pending/blocked/completed) — for workflow tools + Charts (8-color categorical + sequential ramp) — for analytics VALIDATION RULES (Prompt 1b enforces): ✓ Each ramp has minimum 6 steps (50/100/300/500/700/900) ✓ Accent-CTA rule passes: dark-text on accent-500 ≥ 4.5:1 ✓ White-text on accent-500 case explicitly REJECTED unless flagged as "use only on dark surfaces" with annotation ✓ Components reference ONLY Layer 2 aliases, never primitives directly (lint rule) REJECTED palettes (Prompt 1b will fail): ✗ Single-hue strategy (that's Harbor — wrong archetype) ✗ Indigo / purple in any ramp (cliched "AI startup" — Sentinel anti-pattern) ✗ Pastel-only palettes (insufficient contrast for status) ─────────────────────────────────────────────────────────────── WHEN TO PICK SENTINEL ─────────────────────────────────────────────────────────────── Pick Sentinel IF: • Internal tool, B2B SaaS, dashboard, admin product, monitoring tool, analytics product, CRM, project management, dev tools • User session is hours, not minutes • Information density beats whitespace • Multiple status / state combinations needed (workflows, approvals, severities) • Keyboard navigation must be first-class • Charts, tables, or domain-specific data viz required • User base has expertise and expects efficiency over hand-holding Sample adjectives that route to Sentinel (archetype-selection aid — Finding 5 demoted-adjective routing, NOT a generation input): precise · confident · calm · professional · structured · auditable · enterprise · functional · governed · tested · neutral · WCAG-strict · keyboard-first · status-driven If three or more of your brand adjectives are in this list, Sentinel is likely your archetype. Real-world examples (calibrate against these — public products that exemplify Sentinel's principles): • Linear.app (the product, not the marketing site) — light surfaces, hairline borders, accent CTA, dense data • Notion.so (the product) — sentence-case throughout, flat elevation, multi-state badges • Figma's app interface — neutral chrome, color reserved for data and selection • Vercel dashboard — orange accent CTA on light surfaces • Asana / Jira / GitHub Issues — workflow + status badges • Salesforce Lightning — multi-ramp semantic palette • Atlassian's Confluence / Trello — flat with hairlines • AWS Console (newer surfaces) — Sentinel-aligned (older surfaces are pre-Sentinel anti-pattern catalog) DO NOT pick Sentinel if: • Marketing site or brand-forward portfolio → [Harbor](harbor.spec.md) • Mobile-first consumer app with bold, atmospheric feel → [Current](current.spec.md) • Read-focused docs with body text as hero → [Meridian](meridian.spec.md) • Trading desk / observability with 5000+ rows of dense data → [Lattice](lattice.spec.md) • Editorial content where structure should be felt, not seen → [Harbor](harbor.spec.md) ─────────────────────────────────────────────────────────────── FAILURE MODES — what breaks first when Sentinel is misapplied ─────────────────────────────────────────────────────────────── When teams force Sentinel onto the wrong use case, predictable failures appear in this order. 1. Atmospheric flattening (Sentinel on marketing site) Symptom: Marketing site reads as "yet another B2B product page" — flat, dense, no editorial rhythm. Bounce rate climbs. Root cause: Sentinel's compact density + sans-only + flat elevation strip the atmosphere brand sites need. → Switch to [Harbor](harbor.spec.md) (editorial rhythm, warm shadows, generous space). 2. Mobile thumb-misses (Sentinel responsive-down to mobile) Symptom: Buttons feel cramped, sub-44px touch targets, modal dialogs hard to dismiss one-handed, hover-only tooltips invisible on touch. Root cause: Sentinel's compact density doesn't translate to mobile thumb ergonomics; "responsive" can't fix it. → Switch to [Current](current.spec.md) for the mobile shell; keep Sentinel for desktop. 3. Reading fatigue (Sentinel on long-form docs) Symptom: 14px body at 1.5 leading is fine for table rows — exhausting for sustained reading. Eye strain after 3 pages. Root cause: Sentinel optimizes for scan, not read. → Switch to [Meridian](meridian.spec.md) (17–19px body, 1.75 leading, 68ch reading-width). 4. Operator key-shortcut frustration (Sentinel on terminal product) Symptom: Power users complain the product is "slow" — they can do everything in 2 clicks but want to do it in 1 keypress. Sentinel covers keyboard nav but doesn't enforce shortcuts on every action. Root cause: Sentinel is keyboard-friendly; Lattice is keyboard-PRIMARY (every action has a documented shortcut). → Switch to [Lattice](lattice.spec.md) for terminal-grade keyboard-first products. 5. Indigo-purple drift (Sentinel without color discipline) Symptom: Designers reach for indigo / purple / gradient accents to "make it feel modern" and the product starts looking like every other AI startup. Root cause: Sentinel's neutrality + extensible ramps make it easy to drift; without enforcement of the indigo/purple ban, generic SaaS-look creeps in. → Tighten governance: enforce the spec's banned indigo/purple gate at lint time. (Not an archetype switch — a discipline fix within Sentinel.) ─────────────────────────────────────────────────────────────── GOVERNANCE OVERRIDES (Sentinel adds to universal gates) ─────────────────────────────────────────────────────────────── Inherits governance.spec.md in full. Sentinel additionally enforces: ☐ Two-layer token architecture (any component referencing Layer 1 primitive directly fails lint) ☐ Accent-CTA rule enforced (any white-text-on-accent-500 pairing fails CI contrast check) ☐ Tabular numerals required on all numeric columns (font-feature-settings: "tnum" 1) ☐ Typography is fixed px modular (any --text-* declared with clamp() fails lint — that's Harbor) ☐ Sans-serif only (any --font-serif declaration fails lint) ☐ Cold rgba shadows enforced (any oklch shadow fails lint — that's Harbor) ☐ Dark mode tokens defined for every Layer 2 semantic token (governance baseline; Sentinel enforces strictly even if dark mode unshipped) ☐ WCAG verification table required in spec page output (Prompt 08 must enumerate every text/background pairing) ☐ Color-only encoding banned (every severity/status indicator combines color + icon + text label) ☐ "(required)" parenthetical enforced (asterisk-only fails form lint) ─────────────────────────────────────────────────────────────── PHILOSOPHY (paste into prompt context as guiding principle) ─────────────────────────────────────────────────────────────── "Sentinel treats the design system like software: versioned, audited, governed. Voice is a token. Contrast is a contract. Governance is non-negotiable. This is what mature enterprise systems look like." ═══════════════════════════════════════════════════════════════ END SENTINEL SPEC · v1.0 ═══════════════════════════════════════════════════════════════ ``` --- ## Maintenance notes (do not paste into prompts) - **When you extend Sentinel** (new ramp, new domain extension, new component): edit the spec block above, bump the version (`v1.1`, `v1.2`), and re-paste into prompts. - **Conflict with v1 Ch10 prose:** the spec wins. Prose is for understanding *why*; the spec is for generating *what*. - **Domain extensions beyond severity / annotation:** add a new sub-block under DOMAIN EXTENSIONS in this file when a product introduces new semantic ramps (e.g., `--priority-*`, `--status-*`). Document the rule that all domain tokens reference Layer 2 (or Layer 1 primitives) — never raw hex. - **Publishing footer (post-render step, not part of the spec contract):** the rendered HTML at [build/preview/specs/sentinel.html](../../build/preview/specs/sentinel.html) appends an inline credit row as the LAST element inside the existing ``) before committing the new HTML. - **Cross-references:** - Universal predecessor: [governance.spec.md](governance.spec.md) — paste FIRST in every workflow - Companion specs: [harbor.spec.md](harbor.spec.md), [current.spec.md](current.spec.md), [lattice.spec.md](lattice.spec.md), [meridian.spec.md](meridian.spec.md) - Live worked example: [reference/design-system-spec-v1.html](../../reference/design-system-spec-v1.html) (this is what Prompt 08 should produce when fed Sentinel + governance) - Decision tree for picking between archetypes: v1 Ch2 (will be restructured per Finding 5) - Consumed by Prompts 1, 03, 04, 05, 08, 09 (per Finding 12 locked scope)