# Harbor · Archetype Spec Sheet · v1.1 **Status:** authored from v1 Ch9 + Finding 12 mock + design-system-spec parity audit. Source of truth for the editorial / marketing 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 (Harbor-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 (section assembly). **Origin:** [reference/book-v1.html](../../reference/book-v1.html) Ch9 lines 2467–2702. Mock pattern: [finalbookplan.md](../../finalbookplan.md) Finding 12 lines 864–982. Coverage parity check: [reference/design-system-spec-v1.html](../../reference/design-system-spec-v1.html). --- ``` ═══════════════════════════════════════════════════════════════ HARBOR · ARCHETYPE SPEC · v1.1 Editorial / Marketing systems ═══════════════════════════════════════════════════════════════ TAGLINE: an editorial-grade design system for services firms, portfolios, and marketing sites. Structure felt, not seen. PREREQUISITE: governance.spec.md MUST be loaded before this spec. Harbor inherits all universal gates and adds the overrides at the end of this block. ─────────────────────────────────────────────────────────────── THEME ─────────────────────────────────────────────────────────────── Mode: dark-first; light mode is a parallel theme via [data-theme="light"] override (not afterthought) Palette character: warm — off-black surfaces, warm off-white text. NEVER pure #000 or pure #FFF. Reason: editorial reading sessions are longer and more atmospheric than product UI. Warm neutrals reduce visual fatigue and signal curated content. ─────────────────────────────────────────────────────────────── TOKEN NAMING ─────────────────────────────────────────────────────────────── Strategy: SEMANTIC ONLY — no numeric ramps Examples: --color-bg, --color-surface, --color-surface-2, --color-surface-offset, --color-surface-dynamic --color-text, --color-text-muted, --color-text-faint --color-primary, --color-primary-hover, --color-primary-active Banned: --color-primary-50 through --color-primary-900 ramps (that's Sentinel — wrong tool for this archetype) Reason: editorial systems use ~15 surface roles total. Numeric ramps add complexity without payoff at this scale. The AI should think "which role?" not "which step?". ─────────────────────────────────────────────────────────────── COLOR TOKENS (canonical defaults — substitute equivalents) ─────────────────────────────────────────────────────────────── Surfaces (dark mode primary): --color-bg #141312 warm charcoal (page bg) --color-surface #1A1918 default surface --color-surface-2 #1E1D1B raised surface --color-surface-offset #222120 contrast block --color-surface-dynamic #26251F warm-tinted feature block Borders & dividers: --color-divider rgba(255,255,255,0.06) hairline --color-border rgba(255,255,255,0.12) component outline Text (4 levels — no more): --color-text #F5F4F0 warm off-white --color-text-muted rgba(245,244,240,0.70) secondary copy --color-text-faint rgba(245,244,240,0.40) metadata --color-text-inverse #141312 text on accent Accent (single hue, 4 states): --color-primary #66D9C2 teal --color-primary-hover #7EE5D0 hover lift --color-primary-active #55C2AC pressed --color-primary-subtle rgba(102,217,194,0.12) bg tint --color-primary-text #141312 text on teal CTA Semantic trio (NO info level — keep palette restrained): --color-success #7BC97A --color-warning #E8B24D --color-error #E07B6D Focus ring (governance requirement): --color-focus-ring rgba(102,217,194,0.6) teal at 60% ─────────────────────────────────────────────────────────────── TYPOGRAPHY ─────────────────────────────────────────────────────────────── Approach: fluid clamp() for ALL sizes — NO fixed px scale Display family: serif — "Instrument Serif", Georgia, serif Body family: sans — "General Sans", "Inter", sans-serif Display style: italic emphasis on the key word Example: "Structure should be felt, not seen." (set "felt" in serif italic) Scale (9 steps, all clamp): --text-xs clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem) — captions, metadata --text-sm clamp(0.875rem, 0.8rem + 0.35vw, 1rem) — labels, helper text --text-base clamp(1rem, 0.95rem + 0.25vw, 1.125rem) — body default --text-lg clamp(1.125rem, 1rem + 0.75vw, 1.5rem) — leads, sub-heads --text-xl clamp(1.5rem, 1.2rem + 1.25vw, 2.25rem) — section headings (h3, h4) --text-2xl clamp(2rem, 1.2rem + 2.5vw, 3.5rem) — page sub-heads (h2) --text-hero clamp(2.5rem, 1rem + 6vw, 6rem) — page hero (h1, editorial display) Font weights (4 — sufficient for editorial): --weight-regular 400 body, leads --weight-medium 500 buttons, eyebrows --weight-semibold 600 sub-headings --weight-bold 700 headlines (sparingly — italic serif carries most emphasis) Line heights: --leading-tight 1.15 hero + h1/h2 (display) --leading-snug 1.30 h3/h4 (sub-heads) --leading-normal 1.55 body default --leading-relaxed 1.75 long-form lead paragraphs Letter spacing: --tracking-tight -0.02em display headings --tracking-normal 0 body --tracking-wide 0.08em eyebrow/overline (small caps) Reason: editorial reads at any width without media queries. Serif italic display is a curated-content signal that distinguishes editorial from product UI. One declaration, all devices. ─────────────────────────────────────────────────────────────── DENSITY ─────────────────────────────────────────────────────────────── Character: GENEROUS Spacing scale (4px base, 14-step integer scale): --space-1 0.25rem /* 4px tight pair (icon+label) */ --space-2 0.5rem /* 8px default gap */ --space-3 0.75rem /* 12px form field internal */ --space-4 1rem /* 16px card padding */ --space-6 1.5rem /* 24px between related blocks */ --space-8 2rem /* 32px between sections (small) */ --space-12 3rem /* 48px between sections (medium) */ --space-16 4rem /* 64px chapter breaks */ --space-20 5rem /* 80px page section vertical */ --space-32 8rem /* 128px editorial hero padding */ --space-40 10rem /* 160px major hero / between chapters */ Section padding (fluid): --section-padding-y clamp(4rem, 8vw, 10rem) --section-padding-x clamp(1.5rem, 5vw, 6rem) Content widths: --content-narrow 640px reading column, pull quotes --content-default 960px articles, value rows --content-wide 1200px case studies, hero compositions --content-max 1440px full-bleed compositions Reason: magazine-rhythm; whitespace IS the design. Editorial products spend reader attention on fewer, larger elements. ─────────────────────────────────────────────────────────────── ACCENT STRATEGY ─────────────────────────────────────────────────────────────── Strategy: SINGLE HUE — one accent, not a ramp Default accent: teal (#66D9C2) States: 4 only (primary, hover, active, subtle, + text-on-accent) Banned: multi-hue ramps, rainbow palettes, gradient backgrounds, secondary accent ramps, link-color ≠ accent Reason: a single accent is the strongest editorial signal — the page reads as a composition rather than a control panel. ─────────────────────────────────────────────────────────────── ELEVATION ─────────────────────────────────────────────────────────────── Default: elevation via background shift (progressively lighter surface tints), shadows reserved for floating elements ONLY Shadow color: WARM, derived from primary in oklch (NEVER cold black rgba) --shadow-sm 0 1px 2px oklch(from var(--color-primary) l c h / 0.08) card hover --shadow-md 0 4px 16px oklch(from var(--color-primary) l c h / 0.12) dropdown, popover --shadow-lg 0 12px 40px oklch(from var(--color-primary) l c h / 0.18) dialog, drawer --shadow-xl 0 24px 80px oklch(from var(--color-primary) l c h / 0.24) hero overlay, full-screen modal Banned: flat-with-borders for surfaces (that's Sentinel) Banned: strong border + strong shadow on the same element Banned: cold #000-based rgba shadows (sterile against warm palette) ─────────────────────────────────────────────────────────────── RADII ─────────────────────────────────────────────────────────────── Scale (6 steps, moderate — never super-rounded): --radius-sm 4px chips, badges, small inputs --radius-md 8px buttons, cards, dialogs --radius-lg 12px feature cards, hero blocks --radius-xl 16px image frames --radius-2xl 24px pull-quote blocks, major surfaces --radius-full 9999px pills (badges, avatars) Banned: pill-rounded everything, ultra-soft 32px+ on cards (that's Current — too playful for editorial) ─────────────────────────────────────────────────────────────── MOTION ─────────────────────────────────────────────────────────────── --duration-fast 120ms hover color, icon swap --duration-base 200ms default — buttons, dropdowns --duration-slow 350ms dialog open, drawer slide --duration-editorial 600ms section reveal, scroll-spy --ease-out cubic-bezier(0.16, 1, 0.3, 1) --ease-standard cubic-bezier(0.4, 0, 0.2, 1) --transition-ui var(--duration-base) var(--ease-out) Use motion sparingly: hover state changes, scroll-spy active nav, section reveal on enter. Reduced-motion fallback: fade-only at duration-fast. Banned: parallax > 20%, scroll-jacking, animated gradient backgrounds, bouncing micro-animations, marquee. ─────────────────────────────────────────────────────────────── ICONOGRAPHY ─────────────────────────────────────────────────────────────── Family default: PHOSPHOR (light or regular weight) Reason: Phosphor is the only widely-available family with multiple weight variants (thin/light/regular/ bold/fill/duotone). The light + regular weights have the editorial warmth + rounded character that match Harbor's serif italic display + warm oklch shadows. Substitute equivalent thin-line family with weight variants if Phosphor unavailable (Iconoir is closest). NEVER use Lucide for Harbor (too utilitarian — that's Sentinel's territory). Grid: 24px (16px allowed for inline UI) Stroke: 1.5px (light weight) — softer than Sentinel's 2px Color: inherit via currentColor (NEVER hex) Style: line icons only — NO filled icons except severity badges (success/warning/error fill) Density: sparse — icons only where they aid recognition, NEVER as decoration Banned: ✗ Emoji as icon ✗ Multi-color illustrations as icons ✗ Filled circle backgrounds behind icons (gradient circles) ✗ Mixing icon families on the same surface ✗ Animated icons (except spinners and explicit loading states) ✗ Lucide / Material / Tabler families (utilitarian — wrong tone) ─────────────────────────────────────────────────────────────── SECTION TEMPLATES — page composition vocabulary (use ONLY these) ─────────────────────────────────────────────────────────────── 01 HERO EDITORIAL Structure: h1 (clamp 2.5–6rem) + lede (max 56ch) + single CTA Use for: opening sections, page hero Banned: stock photography, hero carousels, multiple CTAs, background video loops, animated text 02 VALUE ROWS Structure: eyebrow + 3–5 numbered rows (01, 02, 03, 04, 05) Each row: number (display serif italic) + heading + 1–2 sentence body Banned: 3-column "icon above title" grid (most cliched layout on the web) 03 ASYMMETRIC SPLIT Structure: 40/60 image+text or 60/40 text+image Banned: 50/50 splits (too symmetric for editorial), image carousels in split 04 METRICS BLOCK Structure: 3 oversized numbers (text-hero) + small labels Background: --color-surface-dynamic (warmer tint) Banned: 4+ metric grid, metric over icon, "+1,247%" hyperbole 05 CASE STUDY Structure: image + bold pull quote (italic serif) + outcome Quote: max-width 52ch, left rule, italic serif, NO quote marks Banned: testimonial slider, headshot circle, star ratings 06 CTA BLOCK Structure: single sentence + single button Banned: multiple CTAs, arrows on submit, "Get Started" copy, background gradient Composition rule: any marketing page is an assembly of these six. The AI assembles, never invents new section types. ─────────────────────────────────────────────────────────────── COMPONENT LIBRARY — generate in this priority order ─────────────────────────────────────────────────────────────── ▼ FOUNDATION (Layer 1 — Prompt 03) 1. Button Variants: primary (teal bg, dark text) / secondary (outline) / ghost (text-only) / destructive (error tint) Sizes: sm (h:32px) / md (h:40px) / lg (h:48px) States: default / hover / focus-visible / active / disabled / loading Harbor rule: arrows ONLY on navigation buttons, NEVER submit Harbor rule: NEVER two primary teal buttons adjacent 2. Icon button Sizes: sm (28px) / md (36px) / lg (44px) Required: aria-label, tooltip on hover/focus Harbor rule: ghost background by default — borders only on dense toolbars 3. Field (text input + textarea) Variants: default / with-icon-leading / with-icon-trailing / textarea States: empty / filled / focus / error / disabled / read-only Harbor rule: labels ABOVE inputs, ALWAYS visible Harbor rule: hint text below input, error text replaces hint BANNED: floating labels (placeholder pretending to be label) 4. Selection controls Checkbox — square 16px, --radius-sm, check icon on fill Radio — circle 16px, dot on fill Switch — track 36×20px, thumb 16px circle, slide animation States: unchecked / checked / indeterminate (checkbox only) / disabled / focus-visible Harbor rule: label always to the right, vertical-align middle 5. Tag / Badge Shape: pill (--radius-full) Variants: neutral / success / warning / error / muted / accent-subtle Sizes: sm (h:20px) / md (h:24px) Harbor rule: max 3 badges adjacent — beyond that, use chips 6. Chip (filter / selection / removable) Shape: --radius-full or --radius-sm (consistent within a surface) Variants: static / removable (with × button) / selectable (with check on selected) Harbor rule: chips for content metadata (categories, tags on articles); rare in pure editorial pages 7. Avatar Sizes: sm (24px) / md (32px) / lg (48px) / xl (96px) Harbor rule: INITIALS ONLY — two-letter monogram on warm surface tint. NEVER stock photo. Real photos acceptable for case-study quote attribution. ▼ COMPOSITE (Layer 2 — Prompt 04) 8. Pull quote Structure: italic serif text, left rule (--color-primary 2px), max-width 52ch Optional: attribution below in --text-sm muted Harbor rule: NO quotation marks (the visual style does the work) 9. Card variants 9a. Card — Flat (default) 1px --color-border, no shadow, --color-surface bg Use for: 90% of cards (services, articles, list items) 9b. Card — Raised No border, --shadow-sm, --color-surface-2 bg Use for: cards that need to float (carousel items, over-image cards) 9c. Card — Interactive Flat + hover lift (translateY -2px, --shadow-sm appears) cursor: pointer, full-card link wrap Use for: clickable card grids (case studies, articles) 9d. Card — Service (Harbor-specific) icon (24px) + h4 heading + 1-2 sentence body + ghost link ("Read more →") 9e. Card — Case study image (16:9 or 4:5) + italic serif pull quote + outcome metric chip 9f. Card — Team avatar (initials only) + name + role + 1-line bio 9g. Card — Stat oversized number (--text-2xl, serif) + label (--text-sm muted, tracking-wide eyebrow) 10. Alert (in-page persistent message) Structure: icon (24px) + title + body + optional action link Variants: info / success / warning / error Harbor rule: warm-tinted background (use semantic at 0.10 opacity, not flat fill) Harbor rule: serif italic on title for editorial feel Banned: pure colored fill (#7BC97A bg with white text — too harsh for editorial palette) 11. Toast (transient notification) Position: bottom-right (desktop) / bottom-center (mobile) Structure: icon + message + dismiss × button Auto-dismiss: 5s default; persistent for errors Animation: fade + slide-up 8px, --duration-base Harbor rule: max 3 toasts stacked; older toasts fade out Banned: slide-in fanfare, sound, modal backdrop 12. Tooltip Trigger: hover (delay 400ms) + focus Position: above default; flip if viewport edge Style: --color-bg solid (NOT translucent), --color-text, --text-xs, max-width 240px Harbor rule: tooltip is a recall aid — use sparingly. Never hide critical info inside a tooltip. 13. Dialog (modal) Structure: title + body + footer (buttons right-aligned) Footer button order: secondary "Cancel" left, primary action right Backdrop: --color-bg at 0.7 opacity, blur 8px 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) Harbor rule: serif italic title for editorial weight 14. Drawer (slide-in panel) Edge: right by default (cart, comments, settings) or top (mobile menu) Width: 400px desktop / full-width mobile Backdrop: same as dialog Required: Esc to close, focus trap Harbor rule: use drawers for content browsing; dialogs for confirmations 15. Tabs Style: underline on active (2px --color-primary), no background fill Navigation: ArrowLeft / ArrowRight cycles tabs Harbor rule: max 5 tabs visible — beyond that, use a dropdown Harbor rule: tabs are for peers (not hierarchy) — never use for navigation between unrelated sections 16. Loading states 16a. Spinner — circle, 24px default, --color-primary stroke, 1s rotation 16b. Progress bar — 4px height, determinate (--progress-fill animated to %) or indeterminate (sliding gradient) 16c. Skeleton — opacity-pulse on neutral block, NEVER gradient shimmer (too feature-y for editorial) Harbor rule: text label required next to spinner for any wait > 1s 17. Nav Style: sticky top, glass-blur backdrop (backdrop-filter: blur(12px)) Active state: scroll-spy with underline on current section Theme toggle: sun/moon icon (icon button) Harbor rule: max 5 top-level items — primary CTA on right, always 18. Process diagram Structure: numbered steps (display serif numbers) + connector lines (1px --color-divider) Layout: horizontal on desktop, vertical on mobile Harbor rule: max 6 steps — beyond that, redesign the content ▼ PATTERNS (Layer 3 — Prompt 05) 19. Form layout Layout: single column, max-width 480–640px, labels above Spacing: --space-4 between fields, --space-6 between groups Required fields: marked with "(required)" inline (NOT asterisk) Submit row: divider above, buttons right-aligned, primary right Harbor rule: NO multi-column forms (editorial reads top-down) 20. Empty state Structure: 64px circle icon (--color-surface-offset bg) + h4 heading + 1-2 sentence body + primary CTA Tone: helpful, not apologetic — "Nothing here yet — start by…" Harbor rule: empty states are an editorial opportunity — use serif italic for emphasis on the encouraging line 21. Article header Structure: eyebrow (category, tracking-wide) + h1 (display italic emphasis on key word) + lede + author/date metadata + hero image (optional, 16:9) Max-width: --content-narrow for h1 + lede; image bleeds wider Harbor rule: NO social-share buttons above the fold 22. Service grid Use INSTEAD of "icon above title" 3-col cliché Structure: 2-col (desktop) or 1-col (mobile), Card — Service variant, alternating split image rows between groups of 4 Harbor rule: descriptions are 1-2 sentences max — link to dedicated page for depth 23. Pricing block Style: max 3 tiers (Starter / Pro / Enterprise pattern), feature list as checkmark rows, single CTA per tier Recommended tier: --color-surface-dynamic background, --color-primary border 1px Harbor rule: NO "popular" badge graphics — use background tint instead Harbor rule: prices in display serif (--text-2xl) with cadence below in --text-sm muted 24. Contact / footer Structure: 3-col on desktop (about + nav + contact), 1-col on mobile, --color-surface-2 background Required: copyright, primary nav repeat, social links (icon buttons, never colored brand fills) Harbor rule: NO newsletter signup in footer — give it its own CTA Block section instead ▼ PRINT BEHAVIOR (Layer 3 — system pattern) Harbor sells marketing pages, case studies, and pricing pages that GET PRINTED. Every Harbor product ships @media print rules by default. Print stylesheet (canonical pattern): @media print { /* Hide chrome and CTAs */ .nav, .reading-progress, .theme-toggle, .cta-block, .newsletter-block, .floating-action { display: none; } /* Force light mode for printing */ :root { --color-bg: #FFFFFF; --color-surface: #FAFAF8; --color-text: #1A1A1A; --color-text-muted: #6B6B6B; } /* Expand body to full printable width */ .article-body, .case-study-body { max-width: none; } /* Show URLs after every link */ a[href^="http"]::after { content: " (" attr(href) ")"; color: var(--color-text-muted); font-size: 0.85em; } /* Page breaks */ h1, h2 { page-break-after: avoid; } .case-study-block, .pricing-tier { page-break-inside: avoid; } .section-divider { page-break-before: always; } /* Pull quotes — keep typographic identity */ .pull-quote { font-family: var(--font-serif); font-style: italic; } /* Drop warm oklch shadows (printer can't render warmth) */ * { box-shadow: none !important; } } Harbor rule: print rules included in the canonical tokens.css output of Prompt 1; no separate print-stylesheet module needed. Harbor rule: case studies and pricing pages MUST print to a single PDF that's pitch-deck-quality (designers and clients print these). ▼ DOMAIN LAYER (Layer 4 — product-specific composites) Domain components are composed FROM Layer 1–3 using Harbor's rules. Each domain component MUST cite which Layer 1–3 primitives it composes and inherit their states + a11y. Below are 5 named examples for editorial / marketing products. Extend per product. 25. Blog post card Composes: Card-Interactive (9c) + Avatar (7) + display serif h2 with italic emphasis on key word Structure: 16:9 image (top) + eyebrow (category, --tracking-wide) + h2 (display serif, italic on one word) + lede (3 lines max, --color-text-muted) + author meta (avatar initials + name + read-time) Harbor rule: entire card is the tap target; image lazy-loads with subtle fade-in (only motion in body content) 26. Author bio block Composes: Avatar (7) + body paragraph + icon buttons (2) Structure: avatar 96px (xl) + h3 name + role line (--text-sm muted) + 2-3 sentence bio + social icon-button row (4 max) Harbor rule: avatar uses INITIALS variant by default (governance override — no stock photos); real photos acceptable only for case-study attribution 27. Service tier card Composes: Card-Service (9d) + Pull quote (8) + numbered list Structure: small icon + h3 service name + 1-paragraph description + numbered "What's included" list (3-5 items) + ghost link "See case studies →" Harbor rule: 2-col grid on desktop (NOT 3-col — that's the banned "icon above title" cliché) 28. Case study testimonial block Composes: Card-CaseStudy (9e) + Pull quote (8) + Card-Stat (9g) Structure: case-study image (4:5) + italic serif pull quote (52ch max, NO quote marks) + outcome stat (oversized number + label) + attribution Harbor rule: outcome stat uses --text-2xl display serif; quote attribution uses --text-sm tracking-wide (eyebrow style) 29. Editorial newsletter inline block Composes: CTA Block (template 06) + Field (3) + Button (1) Structure: short editorial sentence (italic emphasis on key word) + single email field + single primary CTA ("Subscribe" or "Get the Friday letter") Harbor rule: appears ONCE per article, after 60% scroll depth. NEVER as a popup, sticky bar, or scroll-triggered modal (Harbor anti-pattern catalog) Harbor rule: success state replaces the form with a serif italic confirmation line ("Thanks. Check your inbox.") ─────────────────────────────────────────────────────────────── VOICE RULES — apply to ALL generated copy ─────────────────────────────────────────────────────────────── (Inherits governance Voice rules. Harbor adds:) • One primary CTA per section. NEVER two teal buttons adjacent. • Action-first CTA verbs. Forbidden: "Learn More", "Click Here", "Submit", "Get Started", "Discover", "Explore" Use: "Read the case study", "See how we work", "Book a 30-minute call", "See a live demo" • Arrows only on navigation CTAs, NEVER on submit buttons. • Specific claims with numbers over hyperbole. Bad: "Revolutionize your workflow with cutting-edge AI" Good: "Cut expense reports from 45 minutes to 3" • Max line lengths: paragraphs max-width: 68ch leads max-width: 56ch pull quotes max-width: 52ch • Text-wrap tokens: headings text-wrap: balance paragraphs text-wrap: pretty • Italic serif reserved for editorial emphasis (display headlines, pull quotes, key word in a sentence). NEVER use italic for body copy (slows reading). VOICE — Do / Don't pairs: Do → "Read the case study" Don't → "Learn More" Why: zero specificity; AI default slop. Do → "Cut expense reports from 45 minutes to 3" Don't → "Revolutionize your workflow" Why: numbers earn trust; hyperbole erodes it. Do → "Upload failed. The file is over 10MB. Try compressing it." Don't → "Error: Invalid file." Why: What/Why/How formula respects the reader. Do → "We design with restraint." (with "restraint" in serif italic) Don't → "WE DESIGN WITH RESTRAINT." Why: italic carries emphasis; ALL CAPS shouts. ─────────────────────────────────────────────────────────────── BANNED PATTERNS — the Harbor anti-pattern catalog ─────────────────────────────────────────────────────────────── ▼ Token-level antipatterns ✗ Numeric color ramps (--color-primary-50…900) Why: archetype mismatch — that's Sentinel Use: semantic naming (--color-primary, --color-text) ✗ Multi-hue accent ramps (teal + indigo + magenta) Why: editorial reads as control panel Use: single accent hue, 4 states max ✗ Cold #000-based rgba shadows Why: sterile against warm palette Use: oklch shadows derived from --color-primary ✗ Pure black text (#000) Why: harsh on warm backgrounds Use: warm off-black (#141312) ✗ Pure white backgrounds (#FFF) Why: sterile in editorial contexts Use: warm off-white (#F5F4F0) ✗ Fixed px modular type scale Why: fragile across viewports; Harbor reads at any width Use: clamp() for every step ▼ Component-level antipatterns ✗ Floating labels (placeholder-as-label) Why: hides labels on focus; fails autofill; a11y fail Use: labels always visible above inputs ✗ Multiple primary buttons in same section Why: violates one-CTA-per-section rule Use: one primary + one secondary OR one primary + one ghost ✗ Arrows on every CTA Why: visual noise; weakens navigation arrow signal Use: arrows only on navigation links ✗ Strong border + strong shadow on same element Why: double visual weight Use: one or the other, never both ✗ Gradient circle icons Why: signals "generic SaaS" instantly Use: thin-line icons inheriting currentColor ✗ Stock photography of smiling people Why: feels inauthentic; signals template origin Use: product screenshots, abstract imagery, or no imagery ✗ Avatars with stock photos Why: inauthentic; team-page tell Use: two-letter initial monograms on warm tint ✗ Indigo / purple anywhere in palette Why: cliched "AI startup" signal Use: warm accent (default teal) ✗ Card carousels with auto-advance Why: usability fail; editorial wants reader pace Use: stacked cards or swipeable grid (manual only) ✗ Newsletter modal on page load Why: aggressive, breaks reading flow Use: in-content CTA Block section after value content ▼ Copy / voice antipatterns ✗ "Unlock the Power of X" / "Revolutionize Your Workflow" Why: meaningless hyperbole Use: specific claims with numbers ✗ "Get Started" / "Learn More" / "Click Here" CTAs Why: zero differentiation Use: action-first verbs with specificity ✗ Marketing fluff ("Let's embark on…", "Welcome to the future") Why: empty calories; reader skips Use: lead with the specific value ✗ Title Case On Every Heading Why: dated; competes with serif italic emphasis Use: sentence case (governance rule) ✗ Emoji in UI copy (🚀 ✨ 💡) Why: inconsistent rendering, breaks editorial voice Use: SVG icons with currentColor ✗ Italic body copy Why: slows reading; italic should mark editorial emphasis Use: italic serif on display only ▼ Composition antipatterns ✗ 3-column "icon above title" feature grid Why: most cliched layout on the web Use: numbered Value Rows (template 02) or Asymmetric Split (template 03) or Service Grid (pattern 22) ✗ 50/50 image+text splits Why: too symmetric; reads as product UI Use: 40/60 or 60/40 asymmetric ✗ Hero carousel Why: nobody reads slide 2; hides content Use: single Hero Editorial template ✗ Testimonial slider with auto-advance Why: reader pace violation Use: Case Study template (one quote, one outcome) ✗ "As featured in" logo bar above the fold Why: cargo-cult social proof Use: integrate logos into a Case Study or Metrics block ✗ Sticky aggressive CTAs (chat bubble, "talk to us" pulse) Why: breaks editorial atmosphere Use: CTA Block section at natural read pauses ✗ Multi-column body text on desktop Why: editorial reads top-down, not magazine-column Use: single column, max-width 68ch ─────────────────────────────────────────────────────────────── BYOC — REQUIRED COLOR ROLES (Bring Your Own Colors) ─────────────────────────────────────────────────────────────── If you're using Prompt 1b (BYOC variant) instead of Harbor's canonical teal palette, your supplied palette MUST cover these SEMANTIC ROLES. Prompt 1b validates the palette has all 16 required colors before generating tokens.css. Required (16 colors minimum): 1 Page background warm off-black or warm off-white (NEVER pure #000 or #FFF) 2 Surface — default raised one tint from page bg 3 Surface — raised raised two tints from page bg 4 Surface — offset for contrast blocks 5 Surface — dynamic warmer tone for feature blocks (e.g., metrics block bg) 6 Text — primary warm off-white (dark mode) / warm off-black (light mode) 7 Text — muted 70% of primary 8 Text — faint 40% of primary 9 Text — inverse for text on accent CTA 10 Accent — primary the SINGLE hue (Harbor rule) 11 Accent — hover primary lifted ~5% lightness 12 Accent — active primary darkened ~5% lightness 13 Accent — subtle primary at 12% opacity (bg tint) 14 Border — divider hairline (~6% opacity of text) 15 Border — outline component outline (~12% opacity) 16 Focus ring primary at 60% opacity Optional (recommended but not required for validation): + Success / Warning / Error semantic trio (skip "info" — Harbor uses 3 only). Default suggestions provided if absent. REJECTED palettes (Prompt 1b will fail): ✗ Multi-hue ramps (more than ONE accent hue) ✗ Pure #000 / #FFF surfaces or text ✗ Indigo / purple in any role (Harbor anti-pattern) ✗ More than 4 accent states (Harbor rule) ─────────────────────────────────────────────────────────────── WHEN TO PICK HARBOR ─────────────────────────────────────────────────────────────── Pick Harbor IF: • Marketing site, editorial site, brand-forward portfolio, services firm, agency site, content publication, blog, documentation-marketing hybrid • Reader spends 1–3 minutes per session, primarily reading • A single accent hue is sufficient (no need for status ramps, data viz, severity colors) • Session is short, atmospheric, mood-driven • You want structure to be felt, not seen • The brand reads as: warm, editorial, restrained, considered, craft-forward Sample adjectives that route to Harbor (archetype-selection aid — Finding 5 demoted-adjective routing, NOT a generation input): warm · editorial · restrained · considered · craft-forward · atmospheric · curated · serif · quiet · spacious · brand-led · marketing · portfolio · agency-grade · magazine-rhythm If three or more of your brand adjectives are in this list, Harbor is likely your archetype. Real-world examples (calibrate against these — public sites that exemplify Harbor's principles): • Stripe.com homepage — single accent, generous whitespace, serif italic display emphasis • Linear.app marketing site — restrained palette, atmospheric case studies, sparse iconography • Vercel.com marketing — single hue, asymmetric splits, no gradient circle clichés • Apple.com (selected product pages) — editorial rhythm • Mailchimp brand site — warm, illustrated restraint • Notion.so marketing — quiet palette, generous type scale • Most agency portfolio sites — Pentagram, IDEO, Instrument DO NOT pick Harbor if: • Users spend hours per session, doing tasks → [Sentinel](sentinel.spec.md) • Touch targets, gestures, bottom nav matter → [Current](current.spec.md) • Information density beats whitespace → [Lattice](lattice.spec.md) • Body text IS the hero (docs, long-form prose) → [Meridian](meridian.spec.md) • You need 9-step color granularity for status / severity / charts → [Sentinel](sentinel.spec.md) • Mobile-first consumer app with bold saturation → [Current](current.spec.md) ─────────────────────────────────────────────────────────────── FAILURE MODES — what breaks first when Harbor is misapplied ─────────────────────────────────────────────────────────────── When teams force Harbor onto the wrong use case, predictable failures appear in this order. Use these as early-warning signs that the archetype is wrong, not as bugs to fix. 1. Data crowding (Harbor on a dashboard / data product) Symptom: Tables collapse because Harbor's generous spacing leaves no room for rows. 5 rows visible where 50 are needed. Root cause: Harbor's --space-* scale starts at 4px and goes to 160px; product UI needs density. → Switch to [Sentinel](sentinel.spec.md) (compact density) or [Lattice](lattice.spec.md) (max density). 2. Status-color exhaustion (Harbor on a workflow product) Symptom: You start adding a "review" badge color, then "approval pending", then "blocked", then "draft" — running out of accent variants because Harbor allows ONE accent. Root cause: Single-hue rule incompatible with multi-status workflows. → Switch to [Sentinel](sentinel.spec.md) (multi-ramp + semantic). 3. Touch-target failures (Harbor on mobile-first) Symptom: Buttons feel imprecise on phone, taps miss, users complain. Harbor doesn't enforce 44px minimums. Root cause: Harbor is desktop-editorial first; mobile is responsive afterthought. → Switch to [Current](current.spec.md) (44px enforced). 4. Editorial display crowding (Harbor on long-form docs) Symptom: Serif italic display headlines feel showy mid- article; readers complain the page "feels marketing-y". Root cause: Harbor's display-italic emphasis is for hero moments, not body content. → Switch to [Meridian](meridian.spec.md) (utilitarian headings, body-as-hero). 5. The "feels samey" failure (Harbor everywhere on a multi-page site) Symptom: Every page reads atmospheric and slow even when the content is utilitarian (FAQ, status page, search results). Root cause: Harbor's atmospheric rhythm is great for hero surfaces, fatiguing for utility pages. → Use Harbor for hero / brand surfaces only; layer [Sentinel](sentinel.spec.md) or [Meridian](meridian.spec.md) for utility surfaces (per Hybrid Products in governance). ─────────────────────────────────────────────────────────────── GOVERNANCE OVERRIDES (Harbor adds to universal gates) ─────────────────────────────────────────────────────────────── Inherits governance.spec.md in full. Harbor additionally enforces: ☐ Warm oklch shadows (any cold #000-based rgba shadow fails CI) ☐ Single accent enforced (any secondary accent ramp fails lint) ☐ Typography is fluid clamp (any --text-* declared in fixed px fails lint) ☐ Serif italic display reserved for editorial emphasis (no italic body class allowed) ☐ Floating label class banned (fails component lint) ☐ Indigo/purple banned in any token (fails token lint) ☐ Avatar component MUST default to initials variant (stock-photo variant fails review) ☐ One primary CTA per section enforced at template level (template lint flags multi-primary rendering) ☐ Hero variants limited to template 01 (Hero Editorial) — no carousel hero allowed in compiled templates ─────────────────────────────────────────────────────────────── PHILOSOPHY (paste into prompt context as guiding principle) ─────────────────────────────────────────────────────────────── "One accent rule. One primary CTA per section. Labels above inputs. No emoji. No arrows on submits. These aren't stylistic preferences — they're the constraint system that pulls AI output away from the statistical average of the web." ═══════════════════════════════════════════════════════════════ END HARBOR SPEC · v1.1 ═══════════════════════════════════════════════════════════════ ``` --- ## Maintenance notes (do not paste into prompts) - **When you extend Harbor** (new section template, new banned pattern, new component): edit the spec block above, bump the version (`v1.2`, `v1.3`), and re-paste into prompts. Prompts respect whatever they receive. - **Conflict with v1 Ch9 prose:** the spec wins. Prose is for understanding *why*; the spec is for generating *what*. If a contradiction is structural, log it and update Ch9 in v2. - **Publishing footer (post-render step, not part of the spec contract):** the rendered HTML at [build/preview/specs/harbor.html](../../build/preview/specs/harbor.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: [sentinel.spec.md](sentinel.spec.md), [current.spec.md](current.spec.md), [lattice.spec.md](lattice.spec.md), [meridian.spec.md](meridian.spec.md) - 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)