# Style Guide Schema — Layer 3 Specialized Document Type
# KNO Schema Version: 0.2.0
#
# Layer 3 schema that extends document-schema.kno for design systems.
# Defines the structure for visual design specifications.
#
# PURPOSE: Define the schema for design system documents.
# Every file with `type: style-guide` conforms to this schema.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# ENABLES: Design token extraction, CSS generation, component libraries

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KGK3V73J1EA5TG5A6EZ78CV7
slug: style-guide-schema
type: spec
version: 0.2.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Style Guide Schema"
purpose: |
  Define the schema for design system documents.

  **What is a style guide?** A style guide is a .kno document that defines
  the visual design system for a product, brand, or organization. It serves
  as the single source of truth for:

  - Typography (fonts, scales, line heights)
  - Colors (palettes, semantic tokens, themes)
  - Spacing (scales, rhythm, density)
  - Components (buttons, cards, forms)
  - Patterns (interactions, animations, states)

  **Why .kno?** A style guide as .kno enables:
  - **Design token extraction** — Generate CSS custom properties at build time
  - **Type-safe tokens** — TypeScript definitions for design tokens
  - **Cross-platform** — Same tokens for web, mobile, docs
  - **Validation** — Ensure design consistency through schema validation
  - **Versioning** — Track design system evolution with P9 history

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73J1EA5TG5A6EZ78CV7
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - design-systems
    - visual-design
    - typography
    - color-theory
    - ui-components
  keywords:
    - style-guide
    - design-tokens
    - css-variables
    - typography
    - color-palette
    - spacing
    - components

relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "kno@0.0.9 defines the format"

  composes:
    # Inherited through document-schema.kno:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, canonical_id"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation"

  produces:
    # Output formats via conversion:
    - xri: "kno://specs/css-format"
      reason: "Via style-guide-to-css conversion"

  enables:
    # What style guides power:
    - xri: "kno://capabilities/css-generation"
      reason: "Build-time token extraction"
    - xri: "kno://capabilities/component-library"
      reason: "Consistent component styling"
    - xri: "kno://capabilities/documentation"
      reason: "Design system docs"
    - xri: "kno://capabilities/theme-switching"
      reason: "Light/dark/custom themes"

  related_to:
    - xri: "kno://specs/brand-schema"
      reason: "Brand identity uses style guide"
    - xri: "kno://specs/component-schema"
      reason: "Components reference style guide"
    - xri: "kno://specs/css-format"
      reason: "Output format (conversion inferred from produces relationship)"
    - xri: "kno://specs/design-system-review-schema"
      reason: "Sibling schema for design-system review entities (page-scale + ds-scale
        lens framework)"

  projects_to:
    # NEW relationship type (Pass 11 §3.12) — records the auto-generation coupling
    # between style-guide instances and the CSS custom-properties they project.
    # Generators MUST regenerate the projection target on any value change.
    - xri: "kno://services/pspace-site/src/styles/tokens.css"
      reason: "CSS custom-properties projection via
        scripts/generate-css-from-style-guide.ts"
      generator: "scripts/generate-css-from-style-guide.ts"
      regeneration_required_on_change: true

quality:
  completeness: 0.9
  last_reviewed: "2026-01-07"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY (P9 Temporal)
# =============================================================================
_history:
  retention: full
  format: snapshot

  versions:
    - version: "0.2.0"
      date: "2026-05-05"
      author: "claude"
      summary: "Added information_architecture optional_section codifying R-167
        grouped-overflow nav pattern (#2320.c / M58 Phase C)"
      changes:
        - "Added information_architecture optional_section: primary_nav
          (max_visible_tabs=6, grouped-dropdown overflow), sub_route_absorption
          (absorbs[] mechanism), light_dismiss (outside-click + Escape with
          idempotent binding), accessibility (summary/menu/menuitem roles +
          aria-current), nav_surfaces (Header.primaryNav + DocsLayout secondary
          nav), icon_library (lucide via astro-icon)."
        - "No required-field shape change; existing consumers unaffected."

    - version: "0.1.0"
      date: "2026-04-30"
      author: "claude"
      summary: "Pass 11 schema extension — adds 13 new section/policy blocks codifying
        Pass 1-10 canonical rules (R-100…R-941)"
      changes:
        - "Added brand_identity recommended_section (R-100, R-102, R-103, R-105,
          R-106)"
        - "Added typography_invariants recommended_section with hard_tuning_gate
          flag (R-110-R-117)"
        - "Added color_token_policy recommended_section including hex_ban policy
          (R-130-R-135)"
        - "Added container_widths optional_section (R-140-R-143)"
        - "Added footer_contract + hero_aesthetic optional_sections
          (R-144-R-148)"
        - "Added accessibility_floors recommended_section with tiered
          touch-target rule (R-200-R-214)"
        - "Added component_canonicalisation recommended_section registry shape
          (R-300-R-309)"
        - "Added diagram_policy optional_section (R-220-R-228)"
        - "Added motion_policy optional_section (R-380-R-385)"
        - "Added content_voice_policy recommended_section (R-360-R-364,
          R-400-R-404)"
        - "Added tooling_policy optional_section (R-500-R-509)"
        - "Added review_capability optional_section as forward-pointer to new
          design-system-review-schema sibling"
        - "Added projects_to relationship type to track tokens.css generator
          coupling"
        - "Added 15 new validation rules (no_inline_hex_in_components,
          wordmark_text_invariant, deprecated_brand_names_banned,
          kno_vs_dotkno_vernacular, provider_name_banlist,
          spec_version_status_header_required, d2_header_required,
          d2_no_banned_features, d2_comment_prefix_house_style,
          view_transitions_data_astro_rerun, ssr_no_outerhtml_for_state,
          component_jsdoc_spec_source_citation, route_rename_uses_301,
          script_idempotent_init_marker, no_emoji_in_diagrams)"
        - "All additions are additive — no required-field shape change; existing
          consumers continue reading what they read today"
        - "Catalog source: tmp/design-rules-catalog/10-canonical-catalog.md (130
          R-NNN rules)"

    - version: "0.0.3"
      date: "2026-06-02"
      author: "claude"
      summary: "Added guidelines section for prescriptive UX/design patterns"
      changes:
        - "Added guidelines as recommended_section with id, title, applies_to,
          rationale, do, avoid, reference fields"
        - "Distinguishes guidelines (implementation opinions) from principles
          (design philosophy)"

    - version: "0.0.2"
      date: "2026-02-22"
      author: "claude"
      summary: "Extended schema for full .kno-driven CSS pipeline"
      changes:
        - "Added heading_styles and google_fonts_url to typography"
        - "Added navigation, terminal_dots, alternatives to colors"
        - "Added layout section (footer_spacing, max_width)"
        - "Extended shadows and borders descriptions"

    - version: "0.0.1"
      date: "2026-01-07"
      author: "claude"
      summary: "Initial style guide schema"
      changes:
        - "Created Layer 3 schema for design systems"
        - "Defined spec structure with required/optional sections"
        - "Added design token field definitions"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  description: |
    ## What is a Style Guide?

    A **style guide** is a .kno document that defines the complete visual
    design system. Unlike a brand guide (which covers identity, voice, and
    positioning), a style guide focuses on **implementation-ready tokens**
    that can be extracted into CSS, TypeScript, or other formats.

    ## Schema Philosophy

    **Right-sized structure.** The schema defines sections for common design
    concerns (typography, colors, spacing) but doesn't mandate exhaustive
    detail. A minimal style guide might only define colors and fonts.
    A comprehensive one might include animations, accessibility, and
    responsive breakpoints.

    **Token-first.** Every value should be extractable as a design token.
    Instead of prose descriptions, values are structured for machine parsing.

    **Semantic naming.** Tokens use semantic names (`text-muted`, `accent`)
    rather than literal values (`#666`, `#d69e5a`). This enables theming.

  # ===========================================================================
  # REQUIRED SECTIONS
  # ===========================================================================
  required_sections:
    - name: "identity"
      description: "BASIC tier fields (id, type, version)"

    - name: "metadata"
      description: "Name, description, version of the design system"

  # ===========================================================================
  # RECOMMENDED SECTIONS
  # ===========================================================================
  recommended_sections:
    - name: "principles"
      description: "Design philosophy and guiding principles"
      structure:
        type: array
        items:
          name: string
          description: string

    - name: "typography"
      description: "Font families, type scale, line heights"
      structure:
        font_families:
          type: object
          description: "Named font stacks (display, body, mono)"
          fields:
            name: string # e.g., "Source Serif 4"
            fallback: string # e.g., "Georgia, serif"
            css_variable: string # e.g., "--font-serif"
            usage: array # Where this font is used
        type_scale:
          type: object
          description: "Named sizes (xs, sm, md, lg, xl, 2xl, etc.)"
          fields:
            size: string # e.g., "1rem"
            line_height: string # e.g., "1.5"
            usage: string # Description of where used
        heading_styles:
          type: object
          description: "Per-level heading overrides (h1–h6)"
          fields:
            base:
              font_family: string # e.g., "serif"
              font_weight: number # e.g., 600
              line_height: string # e.g., "1.2"
              letter_spacing: string # e.g., "-0.02em"
            h1:
              font_size: string # e.g., "clamp(2rem, 8vw, 2.75rem)"
            h2:
              font_size: string # e.g., "1.75rem"
            h3:
              font_size: string
            h4:
              font_size: string
            h5:
              font_size: string
            h6:
              font_size: string
        google_fonts_url:
          type: string
          description: "Precomposed Google Fonts URL for <link> tag in layout templates"

    - name: "colors"
      description: "Color palette with semantic tokens"
      structure:
        surfaces:
          type: object
          description: "Background surface colors (bg, surface, elevated, inset, tinted)"
        navigation:
          type: object
          description: "Semantic navigation surface aliases (sidebar, top, header)"
        semantic:
          type: object
          description: "Purpose-named colors (success, warning, error, info, stage)"
        terminal_dots:
          type: object
          description: "Terminal window dot color aliases (red, yellow, green)"
        alternatives:
          type: object
          description: "Alternative accent palettes with hover/subtle variants"
        themes:
          type: object
          description: "Theme variations (light, dark)"

    - name: "spacing"
      description: "Spacing scale and layout rhythm"
      structure:
        scale:
          type: object
          description: "Named spacing values (xs, sm, md, lg, xl)"

    - name: "components"
      description: "Reusable UI component specifications"
      structure:
        type: array
        items:
          name: string
          description: string
          variants: array
          states: array
          css_classes: array

    - name: "guidelines"
      description: |
        Prescriptive UX/design patterns that encode this design system's opinions.
        Unlike principles (philosophy, e.g. "Be Honest"), guidelines record concrete
        do/avoid choices with rationale — decisions this system makes that other
        systems might choose differently. They are implementation opinions, not
        universal truths.
      structure:
        type: array
        items:
          id: string # kebab-case identifier, e.g. "left-panel-navigation"
          title: string # Short human-readable title
          applies_to: string[] # Context tags: navigation, layout, forms, dashboard, etc.
          rationale: string # Why this choice was made; what problem it solves
          do: string # The preferred pattern (concrete, actionable)
          avoid: string # The anti-pattern (what NOT to do)
          reference: string # Optional: example pages/components that implement this

    # =========================================================================
    # PASS 11 ADDITIONS — Policy / Invariant blocks (recommended)
    # =========================================================================
    # Added 2026-04-30 in version 0.1.0. Codify Pass 1-10 canonical rules
    # (R-100…R-941) as structural fields. Catalog source:
    # tmp/design-rules-catalog/10-canonical-catalog.md
    # =========================================================================

    - name: "brand_identity"
      description: "Canonical identity, deprecated names, brand-component invariants
        (R-100, R-102, R-103, R-105, R-106)"
      structure:
        canonical_identity:
          name: string # "Forks" | "Possibility"
          status: string # "canonical" | "predecessor" | "parallel"
          revert_evidence: string # Optional commit/PR ref
        deprecated_names:
          type: array
          items:
            name: string # e.g. "Pico", "p9y", "pCo"
            deprecated_at: string # ISO date
            replacement: string # e.g. "Possibility"
        wordmark:
          text: string # e.g. "POSSIBILITY.INC"
          text_invariant: boolean # true — period integral, never split
          font_token: string # e.g. "--font-serif"
          font_weight: number # e.g. 900
        aesthetic_inspirations:
          type: array
          items: string # e.g. ["Dieter Rams functional minimalism", "Terminal aesthetic"]
        vernacular_invariants:
          user_facing: string # e.g. ".kno" — prose form
          identifiers: string # e.g. "kno" — code form

    - name: "typography_invariants"
      description: "Policy-level typography rules — family-role assignments,
        line-height floors, hard-tuning gates (R-110-R-117)"
      structure:
        family_role_invariants:
          type: array
          items:
            levels: string[] # e.g. ["h1","h2","h3"]
            family_token: string # e.g. "--font-serif"
            rationale: string # e.g. "display"
        line_height_floors:
          body_min: number # 1.5 (R-114; WCAG 1.4.12)
          heading_min: number # 1.5
          enforcement: string # e.g. "design-qa-spec"
        fluid_clamps:
          type: array
          items:
            level: string # e.g. "h1"
            clamp: string # e.g. "clamp(2rem, 8vw, 2.75rem)"
        link_state_contract:
          required_states: string[] # ["default","hover","focus-visible","visited"]
        code_chrome_contexts:
          type: array
          items: string # ["inline","block","terminal"]
        hard_tuning_gate:
          enabled: boolean # true
          gate_mechanism: string # e.g. "design-qa spec test re-run required"
          reference: string # path to design-qa spec

    - name: "color_token_policy"
      description: "Policy rules governing colour-token use — hex ban, contrast
        floors, status-state naming, a11y theme variants (R-130-R-135)"
      structure:
        hex_ban:
          enabled: boolean # true (R-131)
          banned_in: string[] # e.g. ["component CSS"]
          allowed_in: string[] # e.g. ["forks_colors source", "tokens.css generator output"]
          enforcement: string # e.g. "lint (rollout per R-941)"
        border_contrast_floor:
          ratio: number # 3.0 (WCAG 1.4.11)
          against: string # e.g. "surface"
        status_token_naming:
          convention: string # "named for state, not colour"
          example: string # e.g. "--color-status-error not --color-status-red"
        accessibility_theme_variants:
          first_class: boolean # true (R-135)
          examples: string[] # e.g. ["colourblind-safe surface tints", "high-contrast theme"]
        logo_mark_token_suffix:
          suffix: string # "-logo-mark"

    - name: "accessibility_floors"
      description: "WCAG-grounded a11y floors with severity per violation
        (R-200-R-214). High-priority block."
      structure:
        skip_link:
          required: boolean # true
          first_focusable: boolean # true
          reveal_pattern: string # e.g. "translateY(-200%) hidden + :focus reveal"
          respects_reduced_motion: boolean # true
          severity_if_missing: string # "BLOCKER"
        landmark_hygiene:
          min_labeled_landmarks: number # 5
          required_landmarks: string[] # ["header","nav","main","aside","footer"]
          severity_if_below: string # "MAJOR"
          severity_if_main_missing: string # "BLOCKER"
        public_docs_crawler_access:
          bot_gating_allowed: boolean # false
          severity_if_violated: string # "BLOCKER"
        use_of_colour:
          requires_triple: boolean # true (colour + icon + word)
          severity_if_violated: string # "MAJOR"
        contrast_floors:
          normal_text_ratio: number # 4.5
          large_text_ratio: number # 3.0
          non_text_ratio: number # 3.0
          enforcement: string # e.g. "design-qa-spec"
          severity_if_violated: string # "BLOCKER"
        focus_ring:
          width_px: number # 2
          offset_px: number # 2
          colour_token: string # e.g. "--color-accent"
          severity_if_missing: string # "MAJOR"
        reduced_motion:
          respected_by_all_motion_components: boolean # true
          severity_if_violated: string # "MAJOR"
        touch_target:
          floor_px: number # 24 (R-209, WCAG 2.5.8)
          target_px: number # 44 (R-210, Apple HIG)
          material_guidance_dp: number # 48 (R-211)
          severity_below_floor: string # "BLOCKER"
          severity_below_target: string # "MAJOR"
        sibling_overlap:
          prohibited: boolean # true
          opt_out_attribute: string # "data-decorative=true"
          severity_if_violated: string # "MAJOR"
        heading_levels:
          allowed_in_prose: string[] # ["h2","h3","h4"]
          severity_if_h5_used: string # "MINOR"
          severity_if_h6_used: string # "MAJOR"
        decorative_marker:
          attribute: string # "data-decorative"
          consumers: string[] # ["design-qa harness", "a11y semantics"]

    - name: "component_canonicalisation"
      description: "Registry of canonicalised components — each entry records the
        canonical implementation + bespoke variants it replaces (R-300-R-309)"
      structure:
        type: array
        items:
          component: string # e.g. "Wordmark"
          spec_anchor: string # e.g. "content/forks-style-guide.kno#components.wordmark"
          file: string # e.g. "services/pspace-site/src/components/Wordmark.astro"
          replaces_bespoke: string[] # e.g. [".logo", ".home-logo", ".invite-logo"]
          props_enum:
            type: object # e.g. { size: ["sm","md","lg"] }
          severity_invariants: string[] # e.g. ["focus-ring 2px", "POSSIBILITY.INC text invariant"]
          single_source_of_truth: boolean # true

    - name: "content_voice_policy"
      description: "Editorial conventions, vernacular, provider-opacity,
        identity-vs-tenant separation (R-360-R-364, R-400-R-404)"
      structure:
        provider_opacity:
          enabled: boolean # true
          banned_tokens: string[] # e.g. ["keycloak","cloudflare","sendgrid",…]
          allowed_contexts: string[] # e.g. ["troubleshooting","vendor_specific:true","metadata"]
          enforcement: string # e.g. "pre-commit (strict mode)"
        identity_vs_tenant_separation:
          required_in_public_copy: boolean # true
          reference_doc: string # e.g. "content/knowledge-base/identity-vs-tenant-rbac.kno"
        public_copy_vocabulary: string # e.g. "OIDC standard claims (sub, email, name)"
        agent_policy_source_of_truth: string # e.g. "content/agent-policy.kno"
        unicode_glyphs_preferred_over_emoji: boolean # true
        ascii_box_alignment_required: boolean # true
        component_jsdoc_requires_spec_source_citation: boolean # true
        canonicalisation_framing_phrase: string # e.g. "replaces N bespoke"

  # ===========================================================================
  # OPTIONAL SECTIONS
  # ===========================================================================
  optional_sections:
    - name: "shadows"
      description: "Box shadow definitions (sm, md, lg, inset)"
    - name: "borders"
      description: "Border radius and width scales (none, xs, sm, md, lg, full)"
    - name: "layout"
      description: "Layout tokens (footer_spacing, max_width)"
    - name: "transitions"
      description: "Animation timing and easing"
    - name: "breakpoints"
      description: "Responsive design breakpoints"
    - name: "z_index"
      description: "Stacking context layers"
    - name: "icons"
      description: "Icon system specification"
    - name: "syntax_highlighting"
      description: "Code block color scheme"

    # =========================================================================
    # PASS 11 ADDITIONS — Optional policy/structure blocks
    # =========================================================================
    # Added 2026-04-30 in version 0.1.0. See top-of-file changelog.
    # =========================================================================

    - name: "container_widths"
      description: "Named container width tiers (R-140-R-143). Default 960 / wide 1200
        / extra-wide 1440 / prose 720."
      structure:
        type: array
        items:
          tier: string # "default" | "wide" | "extra-wide" | "prose"
          width_px: number # 960 | 1200 | 1440 | 720
          use_cases: string[] # e.g. ["Dashboard pages","forms"]

    - name: "footer_contract"
      description: "Required footer elements (R-144-R-146). Brand nav, meta
        date/version, edit link."
      structure:
        required_elements:
          type: array
          items:
            element: string # "brand_nav" | "meta_date_version" | "edit_link"
            required: boolean
            source: string # e.g. ".kno provenance.last_updated", "page slug"

    - name: "hero_aesthetic"
      description: "Page hero / terminal aesthetic invariants (R-147, R-148)"
      structure:
        border_radius: string # "0" — Rams hard-edge
        border_width: string # e.g. "2px"
        height_tokens:
          use_dual_min_height: boolean # true (100vh + 100dvh)
          footer_offset_token: string # e.g. "--footer-height"

    - name: "diagram_policy"
      description: "D2/Mermaid diagram conventions (R-220-R-228)"
      structure:
        d2:
          canonical_theme:
            id: number # 200
            name: string # "Mauve"
          comment_prefix: string # "#"
          comment_prefix_alternates_permitted: string[] # ["//"] discouraged
          banned_features: string[] # ["steps","scenarios","layers"]
          complex_layout_engine: string # "elk"
          header_required_fields: string[] # ["name","version","status","last_updated","description"]
          colour_source: string # "forks_colors"
          inline_hex_allowed: boolean # false
        mermaid:
          direction_vocabulary: string[] # ["TB","BT","LR","RL"]
        theme_purpose_enum: string[] # ["production","ab-test","dev-only"]

    - name: "motion_policy"
      description: "Motion / View Transitions / SSR-client-consistency rules (R-380-R-385)"
      structure:
        toggle_dont_replace:
          enabled: boolean # true
          forbidden_apis: string[] # ["outerHTML","innerHTML"] for state changes
        ssr_renders_all_states: boolean # true
        inline_define_vars_requires_data_astro_rerun: boolean # true
        when_to_use_css_transitions: string[] # ["hover","focus","transform","opacity","class-toggle"]
        when_to_use_js_animations: string[] # ["<details>","height-to-auto","Web Animations API only"]
        action_modal_close:
          use_custom_event: boolean # true
          forbidden: string[] # ["window.location.reload"]
        event_delegation_required_for_dynamic: boolean # true

    - name: "tooling_policy"
      description: "Lint rollouts, audit cadence, enforcement layers (R-500-R-509)"
      structure:
        promote_threshold:
          instances: number # 3 — promote pattern to component or lint
        lint_rollout_steps: string[] # ["warn","soft-fail","strict"]
        retro_audit_tier_model:
          phase: string # "mini-retro + scoped audit (5 spot checks)"
          epic: string # "code-auditor"
          milestone: string # "code-auditor"
        design_qa_harness:
          enabled: boolean # true
          dimensions: string[] # 7 dimensions
        enforcement_layers: string[] # ["edge","origin","runtime","dcr"]
        route_rename_redirect_codes:
          seo_bearing_rename: number # 301
          method_preserving_rename: number # 308
        script_idempotence_required: boolean # true (data-astro-rerun + duplicate-listener guard)

    - name: "review_capability"
      description: "Optional binding to a design-system-review-schema instance.
        Forward-pointer that lets a style-guide entity declare which review
        schema reviews target it."
      structure:
        schema: string # e.g. "kno://specs/design-system-review-schema@0.1.0"
        review_mode_enum: string[] # ["page-scale","ds-scale"]

    - name: "information_architecture"
      description: "Nav-shape rules covering the grouped-overflow pattern, sub-route
        absorption, light-dismiss, and accessibility for primary and secondary
        navs (#2320.c / R-167)."
      structure:
        primary_nav:
          max_visible_tabs: number # 6
          overflow_strategy: string # "grouped-dropdown"
          overflow_label: string # "More"
          overflow_icon: string # Lucide icon name
          element: string # "<details>/<summary>"
          rationale: string
        sub_route_absorption:
          enabled: boolean
          mechanism: string # "absorbs[]"
          highlight_parent_on_subroute: boolean
        light_dismiss:
          required_for: string[] # ["<details> overflow menus"]
          triggers: string[] # ["outside-click","Escape"]
          idempotent_binding_pattern: string # "documentElement.dataset.<flag>Bound = '1'"
          script_directive_required: string # "data-astro-rerun"
          reference_component: string # path
        accessibility:
          summary_role: string # "button"
          menu_role: string # "menu"
          menuitem_role: string # "menuitem"
          aria_haspopup_required: boolean
          aria_current_page_required_for_active: boolean
        nav_surfaces:
          header_primary_nav:
            consumed_by: string
            scope: string
          docs_secondary_nav:
            consumed_by: string
            scope: string
            loader: string
        icon_library: string # "lucide"
        icon_via_package: string # "astro-icon"
        framework_version: string # "1.0"
        framework_reference: string # path/URL to the lens-framework spec
        cluster_inferred: number # 1-5 (R-908)
        ds_definition: string # one of: library | discipline | gateway | multi-ds-portal | multi-context

  # ===========================================================================
  # VALIDATION RULES
  # ===========================================================================
  validation:
    rules:
      - name: "css_variable_naming"
        description: "CSS variables should use kebab-case with -- prefix"
        pattern: "^--[a-z][a-z0-9-]*$"

      - name: "color_format"
        description: "Colors should be hex (#fff, #ffffff) or CSS variables"
        pattern: "^(#[0-9a-fA-F]{3,8}|var\\(--[a-z][a-z0-9-]*\\))$"

      - name: "size_format"
        description: "Sizes should include units (rem, px, em, %)"
        pattern: "^[0-9.]+(rem|px|em|%|vh|vw)$"

      # =======================================================================
      # PASS 11 ADDITIONS — codify Pass 1-10 canonical rules as lints
      # =======================================================================
      # Added 2026-04-30 in version 0.1.0. Each maps to one or more R-NNNs in
      # tmp/design-rules-catalog/10-canonical-catalog.md. Lints land in
      # follow-up Issues using the 3-step rollout per R-501 (warn → soft-fail
      # → strict).
      # =======================================================================

      - name: "no_inline_hex_in_components"
        description: "Component CSS must reference var(--color-*); no hex literals (R-131)"
        rollout: warn
      - name: "no_emoji_in_diagrams"
        description: "Diagrams (D2/Mermaid/ASCII) must use Unicode glyphs, not emoji
          (R-400)"
        rollout: warn
      - name: "wordmark_text_invariant"
        description: "Wordmark component must render exactly 'POSSIBILITY.INC' — period
          integral, never split (R-102)"
        rollout: strict
      - name: "deprecated_brand_names_banned"
        description: "Pico, p9y, pCo banned in user-facing copy (R-103)"
        rollout: warn
      - name: "kno_vs_dotkno_vernacular"
        description: "Use '.kno' in prose, 'kno' (lowercase) in identifiers (R-104)"
        rollout: warn
      - name: "provider_name_banlist"
        description: "Banned provider tokens (keycloak, cloudflare, sendgrid, …) unless
          in allowed_contexts (R-360, R-361)"
        rollout: strict
      - name: "spec_version_status_header_required"
        description: "Every spec declares Version and Status, in either '# Version'/'#
          Status' comment-header form OR YAML 'version:'/'status:' field form
          (R-340; dual-acceptance per #2287)"
        rollout: warn # 62 baseline findings as of #2287 (down from 116); advance to soft-fail once <20
      - name: "d2_header_required"
        description: "Every D2 file has a header block with
          name/version/status/last_updated/description (R-228)"
        rollout: warn
      - name: "d2_no_banned_features"
        description: "D2 files must not use steps, scenarios, layers (R-223)"
        rollout: warn
      - name: "d2_comment_prefix_house_style"
        description: "D2 comments use # (warning if //) (R-221)"
        rollout: warn
      - name: "view_transitions_data_astro_rerun"
        description: "<script define:vars> blocks add data-astro-rerun (R-382)"
        rollout: warn
      - name: "ssr_no_outerhtml_for_state"
        description: "JS state-change MUST NOT use outerHTML/innerHTML — toggle
          data-attributes instead (R-380)"
        rollout: warn
      - name: "component_jsdoc_spec_source_citation"
        description: "Component jsdoc references the .kno anchor it implements (R-403).
          Per #2288 Path B, only enforced for components first introduced
          on/after CUTOFF_DATE 2026-04-30; existing components are
          grandfathered. Use --all to audit pre-cutoff backfill candidates"
        rollout: warn # 0 baseline post-cutoff; 48 pre-cutoff grandfathered (run --all to audit)
      - name: "route_rename_uses_301"
        description: "SEO-bearing route renames use 301; method-preserving renames use
          308 (R-508). Scope broadened per #2286 to handlers + routes + modules;
          suppress intra-flow redirects with `R-508-allow:` marker"
        rollout: warn # 0 baseline findings — genuine (API issues no HTTP redirects); promote to soft-fail when first redirect ships
      - name: "script_idempotent_init_marker"
        description: "Inline scripts under View Transitions carry duplicate-listener
          guard (R-509)"
        rollout: warn

  # ===========================================================================
  # EXAMPLE STRUCTURE
  # ===========================================================================
  example:
    minimal: |
      id: my-style-guide
      type: style-guide
      version: 0.1.0
      title: "My Style Guide"
      purpose: "Design system for my app"

      design_system:
        name: "My Design System"
        typography:
          font_families:
            body:
              name: "Inter"
              css_variable: "--font-sans"
        colors:
          semantic:
            bg: "#ffffff"
            text: "#1a1a1a"
            accent: "#0066cc"

    comprehensive: |
      # See docs/design/forks-style-guide.kno for full example
      # with typography, colors, spacing, components, and themes.

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [ id, type, version, style-guide-schema ]
  - path: "spec/fields"
    line: 80
    keywords: [ title, brand, typography, colors, spacing ]
  - path: "spec/tokens"
    line: 150
    keywords: [ design-tokens, css-variables, semantic-colors ]
  - path: "spec/components"
    line: 200
    keywords: [ components, buttons, forms, cards ]
  - path: "examples"
    line: 250
    keywords: [ minimal, comprehensive, tokens ]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [ id, type, version ]
  - xri: "#spec"
    role: section
    title: "Style Guide Schema"
    keywords: [ tokens, typography, colors ]
  - xri: "#examples"
    role: section
    title: "Usage Examples"
    keywords: [ minimal, comprehensive ]