onto-mcp 0.3.0

package/.onto/domains/visual-design/dependency_rules.md

@@ -0,0 +1,282 @@
+---
+version: 2
+last_updated: "2026-04-16"
+source: manual
+status: established
+---
+
+# Visual Design Domain — Dependency Rules
+
+Classification axis: **linkage type** — dependencies classified by the type of relationship between visual design elements and systems.
+
+## Token–Component Dependency
+
+### Token Reference Direction
+
+- Primitive Token → Semantic Token → Component Token: tokens must reference in the direction of lower → upper (unidirectional). If semantic tokens directly contain raw values, theme switching becomes impossible
+- Dependency chain: Raw Value → Primitive Token Definition → Semantic Token Reference → Component Token Reference → Component Visual Property
+- Violation example: a design system defined `button-bg: #2563EB` directly. When dark mode was added, the blue that worked on white backgrounds became invisible on dark surfaces. Restructuring to `button-bg: color-primary` → `color-primary: blue-500` (light) / `color-primary: blue-300` (dark) resolved this
+
+### Component → Token Binding
+
+- A component's visual properties must reference semantic tokens. Using hardcoded values directly makes consistency maintenance impossible
+- Verification: for each component visual property (background, border, text color, shadow, spacing, border-radius), confirm a token reference exists. Hardcoded values = violation
+- Case study: a product had 47 distinct button background colors because developers copied hex values from design tool screenshots instead of referencing tokens. Migrating to token references and consolidating to 5 semantic button colors reduced visual inconsistency across 200+ screens
+
+### Semantic Token Change → Propagation
+
+- Changing a semantic token value affects all components referencing that token. Impact scope verification before change is mandatory
+- Change chain: Semantic Token Value Change → Identify All Referencing Component Tokens → Verify Each Component's Visual Integrity → Verify Contrast Ratios → Approve Change
+- When adding a new token: first verify whether an existing token can express the intent. Unnecessary token growth increases system complexity. Threshold: if a new semantic token is proposed, check whether it is used by 2+ components. Single-use semantic tokens are candidates for component tokens instead
+
+## Typography–Layout Dependency
+
+### Type Scale → Visual Hierarchy
+
+- A type scale must be defined before visual hierarchy between text elements can be established. Without a scale, heading sizes are arbitrary and hierarchy is inconsistent
+- Dependency chain: Base Size Selection → Ratio Selection → Scale Generation → Role Assignment (display/h1/h2/h3/body/caption)
+- Failure mode: a marketing site defined headings at 32px, 28px, 24px (arbitrary steps). The 28px and 24px levels were nearly indistinguishable. Switching to a 1.25 scale (16, 20, 25, 31.25) produced clear, harmonious size differences
+
+### Type Scale → Spacing System
+
+- Text size provides the basis for surrounding spacing. Larger text requires proportionally more spacing above and below
+- Dependency: heading spacing > body text spacing. A heading with the same spacing as body text appears cramped; body text with heading-level spacing appears isolated
+- Verification: for each type scale level, confirm that the associated spacing creates visual grouping — text and its content are closer together than text and adjacent sections
+
+### Measure → Grid Column Width
+
+- The optimal readability measure (45~75 characters) constrains grid column width. Grid design must not produce text blocks that exceed or fall far below this range
+- Calculation: at 16px body text, average character width is ~8px. Optimal measure (60 characters) = ~480px. A 12-column grid with 24px gutters on a 1440px screen produces ~96px columns; a 5-column text block = ~480px — within range
+- Violation example: a 2-column layout on desktop placed body text in columns 1~8 (768px wide), producing ~96 characters per line. Users reported difficulty finding the next line start. Constraining text to columns 1~6 (576px, ~72 characters) resolved the issue
+
+### Typeface Change → Full Typography Re-verification
+
+- Different typefaces have different x-height, character width, and line-height characteristics. Changing a typeface requires re-verification of scale, line-height, measure, and spacing
+- Change chain: New Typeface Selection → x-height Comparison → Line-height Adjustment → Measure Re-verification → Spacing Review → Type Scale Tuning → Visual Regression Test
+- A typeface with significantly larger x-height than the previous one may make the same pixel size feel larger, requiring scale adjustments across the system
+
+## Color–Accessibility Dependency
+
+### Color Palette → Contrast Verification
+
+- After defining colors, verify that WCAG contrast criteria are met in all usage contexts (text/background, icon/background, UI component/adjacent color)
+- Dependency chain: Palette Definition → Usage Context Mapping → Contrast Ratio Calculation → Failure Identification → Color Adjustment or Context Change
+- Verification scope: every foreground-background combination in the system, not just the "primary" combinations. Edge cases (light gray text on white, dark blue text on dark gray) are where failures hide
+
+### Color Palette Change → Accessibility Re-verification
+
+- If any color in the palette changes, contrast re-verification of all combinations using that color is needed
+- Proportional impact: changing a primary color affects more combinations than changing an accent color. The propagation scope depends on the changed token's reference count
+- Case study: a brand refreshed its primary green from `#2E7D32` to `#4CAF50` (lighter, more vibrant). The new green failed contrast (3.2:1) against white backgrounds for normal text. Adding a dark variant `#2E7D32` for text use while keeping `#4CAF50` for large elements resolved the conflict
+
+### Semantic Color → Supplementary Means
+
+- Semantic colors (error, success, warning) must always be accompanied by supplementary means other than color
+- Required supplementary means per semantic meaning:
+  - Error: red + exclamation icon + descriptive text
+  - Success: green + checkmark icon + confirmation text
+  - Warning: amber/yellow + warning triangle icon + guidance text
+  - Info: blue + info circle icon + explanatory text
+- Violation: a form validation system showed only a red border on invalid fields. Color-blind users could not distinguish error fields from normal fields. Adding an error icon and inline error text message resolved this
+
+### Dark Mode Addition → Full Color System Redefinition
+
+- Dark mode is not an inversion of light mode colors. It requires a separate semantic token mapping
+- Dark mode specific rules: (1) reduce saturation of colored surfaces, (2) elevated surfaces use lighter backgrounds (opposite of light mode shadows), (3) text colors adjust for comfortable reading on dark backgrounds, (4) all contrast ratios re-verified
+- Dependency chain: Dark Mode Decision → Separate Primitive Set (dark) → Semantic Token Remapping → All Component Contrast Re-verification → Image/Icon Adaptation → System Preference Detection
+
+## Brand–Visual System Dependency
+
+### Brand Colors → Color System
+
+- Brand colors constrain the primary/accent colors of the color system. Choosing primary colors unrelated to brand colors violates brand alignment
+- Dependency chain: Brand Guideline Colors → Design System Primitive Tokens → Semantic Token Mapping → Component Application
+- When brand colors do not form a complete palette (common — brand guidelines define 2~3 colors), the design system extends the palette with neutral colors and complementary/analogous hues derived from the brand colors
+
+### Brand Typeface → Typography System
+
+- When a brand typeface is designated, it constrains typeface selection in the typography system
+- Dependency chain: Brand Typeface → Typography System Primary Face → Pairing Typeface Selection → Type Scale Definition
+- If the brand typeface has poor screen readability (e.g., a display typeface meant for headings), restrict it to headings and select a complementary readable typeface for body text
+
+### Brand Tone and Manner → Visual Element Choices
+
+- If the tone is "professional and restrained," elaborate illustrations, bright saturated colors, and playful typefaces are inappropriate. Tone constrains all visual choices
+- Verification: for each visual element decision (typeface, color, icon style, image style, motion style), confirm alignment with the documented tone. Misalignment = brand drift
+
+### Brand Guideline Change → Full Visual System Review
+
+- Brand identity is a higher-level constraint on the visual system. Changes have a large propagation scope
+- Change chain: Brand Guideline Update → Identify All Brand-Coupled Tokens → Re-verify Brand Alignment → Update Design System → Re-verify Accessibility → Propagate to Code → Visual Regression Test
+- Transition period: define coexistence duration for old and new brand elements. Without a defined period, both versions proliferate indefinitely
+
+## Component–State Dependency
+
+### Component Definition → State Definition
+
+- All interactive components must have at least 5 states visually defined: default, hover, active, focus, disabled
+- Extended states for stateful components: loading, error, selected (total 8 states — see structure_spec.md §State System)
+- Failure mode: a toggle switch component defined only default and active states. When users tabbed to it (focus state undefined), there was no visible indication of keyboard focus
+
+### State Definition → Motion Definition
+
+- If visual state transitions exist, the easing and duration of the transition must be defined
+- Dependency: state pair → transition definition. Default→Hover: 150ms ease-out. Hover→Active: 100ms ease-in. Any→Focus: instant (0ms or crossfade). Any→Disabled: 200ms ease-out
+- Without transition definitions, implementations vary: some developers add 0ms (jarring), others add 500ms (sluggish). Defining transitions prevents this divergence
+
+### Component Variant Addition → All States Required
+
+- When adding a new variant, all states of that variant must be defined. Partial definition causes arbitrary interpretation during implementation
+- Verification: variant × state matrix. Every cell must have a visual specification. Empty cells = incomplete definition
+
+## Design Tool–Code Dependency
+
+### Design Tool Component → Code Component
+
+- Components defined in design tools (Figma) must be implementable in code. Bidirectional synchronization frequency must be defined (e.g., weekly token sync, per-sprint component sync)
+- Failure mode: Figma components using effects (blur, blend modes) that are not reproducible in CSS without performance impact. Design tool capabilities must be constrained by implementation feasibility
+
+### Design Token → Code Variable
+
+- Design tokens are converted to CSS custom properties, style constants, or platform-specific variables in code. A conversion pipeline must exist (e.g., Style Dictionary, Tokens Studio)
+- Dependency chain: Design Token (Figma/JSON) → Token Build Pipeline → CSS Custom Properties / Swift Constants / Kotlin Values → Component Styles
+- Without a pipeline, tokens are manually copied — introducing transcription errors and drift over time
+
+### Discrepancy Resolution
+
+- Prior agreement on which side is the source of truth is needed. Without agreement, discrepancies evolve independently, causing drift
+- Recommended model: **design system documentation** (not Figma, not code) is the source of truth. Both Figma and code are implementations that must conform to the documentation. When they disagree, the documentation resolves the conflict
+- Acceptable discrepancy: implementation-specific adaptations (CSS shadow rendering differs slightly from Figma shadow) within defined tolerance. Unacceptable: different colors, different spacing values, missing states
+
+## Accessibility–Motion Dependency
+
+### Motion Definition → prefers-reduced-motion Support
+
+- All elements with motion must have a reduced-motion alternative defined. This is not optional — it is a WCAG requirement (2.3.3 AAA, widely adopted as AA baseline)
+- Dependency chain: Motion Element Identified → Motion Purpose Documented → Reduced-Motion Alternative Defined → prefers-reduced-motion Media Query Implemented → Visual State Change Still Communicated
+- The alternative must communicate the same state change without motion. Replace animation with instant transition (opacity crossfade at 0ms or very short duration), not with complete removal
+- Violation example: a dashboard used animated bar chart transitions to show data changes. When prefers-reduced-motion was active, bars updated without any visual feedback — users couldn't tell when data refreshed. Adding an instant value change with a brief highlight (background flash without motion) resolved this
+
+### Auto-playing Content → Pause Mechanism
+
+- Automatically moving content (carousels, auto-scrolling feeds, video backgrounds) must be pausable by the user (WCAG 2.2.2)
+<!-- derived-from: WCAG 2.2, SC 2.2.2 -->
+- Dependency chain: Auto-playing Element Identified → Pause Control Visible → Pause State Persistent → Resume Available
+- The pause control must be visible without scrolling or searching. A pause button hidden behind a hover state on the carousel itself is insufficient for keyboard and screen reader users
+
+### Flashing Content → Absolute Restriction
+
+- Content that flashes more than 3 times per second can trigger seizures (WCAG 2.3.1). This is an absolute prohibition
+<!-- derived-from: WCAG 2.2, SC 2.3.1 -->
+- Scope: all visual changes including animated GIFs, video content, loading animations, and transition effects
+- Verification: analyze all animated elements for flash frequency. Tools: Photosensitive Epilepsy Analysis Tool (PEAT)
+- No exceptions: this prohibition cannot be overridden by any other design consideration, brand requirement, or stakeholder request
+
+## Responsive–Visual Dependency
+
+### Viewport Size → Typography Adaptation
+
+- Type scale must adapt to viewport size. The same heading size appropriate for desktop (e.g., 48px) may be too large for mobile
+- Dependency chain: Viewport Width → Breakpoint Threshold → Type Scale Adjustment → Line-height Re-check → Measure Re-check → Vertical Spacing Adjustment
+- Implementation: fluid typography (`clamp()`) or per-breakpoint scale definitions. Both are valid; fluid is smoother but harder to debug
+- Constraint: minimum sizes (body ≥16px, caption ≥12px) must be maintained at all viewports
+
+### Viewport Size → Spacing Adaptation
+
+- Spacing values may need to reduce on smaller viewports to maintain content density without horizontal overflow
+- Dependency: if spacing remains constant while viewport shrinks, eventually content overflows or becomes cramped
+- Approach: define compact spacing scale for mobile (typically 75% of desktop values), but never below touch target minimums
+
+### Viewport Size → Grid Adaptation
+
+- Grid column count and gutter width change at breakpoints. Content must reflow to accommodate fewer columns without information loss
+- Dependency chain: Viewport Width → Breakpoint → Column Count Change → Content Reflow → Priority Preservation → Touch Target Verification
+- Content loss prohibition: no content may be permanently hidden in responsive transitions. Content may be collapsed, reorganized, or moved to alternative locations, but must remain accessible
+
+## Circular Dependency Detection and Classification
+
+In visual design, some apparent circular dependencies are intentional patterns, while others indicate structural defects.
+
+### Intentional Circular Patterns
+
+- **Token ↔ Theme**: tokens define visual properties; themes redefine token values. This is not a cycle — it is a controlled override mechanism. Management: the token system defines the structure; themes override primitive values only
+- **Brand ↔ Design System**: brand guidelines constrain the design system; the design system feeds back into brand guidelines when digital-specific needs arise. Management: brand guidelines are the higher authority for identity decisions; the design system is the higher authority for digital implementation decisions
+- **Grid ↔ Typography**: grid column width constrains measure; type scale affects spacing which affects grid gutters. Management: choose one as the starting point (usually type scale) and derive the other
+
+### Unintentional Circular Dependencies (Defects)
+
+- **Token ↔ Token**: semantic token A references semantic token B, and B references A. Resolution: flatten — one must reference a primitive directly
+- **Component ↔ Component**: component A's visual spec depends on component B's dimensions, and B depends on A. Resolution: extract the shared dimension into a token
+- **Brand ↔ Accessibility**: brand colors adjusted for accessibility fed back into brand guidelines, then brand guidelines re-adjusted for aesthetics, creating a loop. Resolution: establish accessibility as the non-negotiable baseline; brand adjusts once and the result is the new brand color
+
+### Detection Method
+
+For any bidirectional dependency between elements X and Y:
+1. **Identify the source of truth**: is there a clear owner? If yes → intentional (document the SoT). If no → defect
+2. **Trace the reference chain**: does the chain terminate at a primitive value? If yes → not a cycle. If it loops → defect
+3. **Check for infinite loops**: can a token change cascade back to itself? If yes → structural defect regardless of intent
+
+## Referential Integrity
+
+### Token Reference Integrity
+
+- Every semantic token must reference an existing primitive token. Broken references (semantic token pointing to a deleted primitive) produce undefined visual properties
+- Every component token must reference an existing semantic token
+- Verification: automated token reference validation as part of the design system build pipeline
+
+### Cross-File References
+
+- design_scope.md sub-areas referenced in competency_qs.md must exist and match the CQ-ID mapping
+- logic_rules.md sections referenced in competency_qs.md inference paths must exist
+- structure_spec.md structural requirements referenced in dependency_rules.md must exist
+- Verification: grep all `→` and `§` references and confirm targets exist
+
+### Design Tool–Code References
+
+- Components in Figma must have corresponding code components (or documented exceptions)
+- Token values in Figma must match code variables (within defined tolerance)
+- Verification: per-sprint comparison of Figma token values vs code custom property values
+
+## Source of Truth Management
+
+### Internal Source of Truth
+
+- **Visual design decisions**: source of truth is the design system documentation (token definitions, component visual specs). Not Figma, not code — documentation
+- **Brand visual decisions**: source of truth is the brand guidelines document. If the design system and brand guidelines conflict on a brand element, the brand guidelines prevail
+- **Accessibility criteria**: source of truth is WCAG official documentation and the organization's accessibility policy
+
+### External Source of Truth
+
+- **Accessibility standards**: WCAG 2.2 AA (minimum), applicable accessibility laws. Non-negotiable baseline
+- **Platform visual guidelines**: Material Design 3 (Android), Apple HIG (iOS/macOS). Define platform-specific visual conventions
+- **Color standards**: ICC color profiles for cross-device consistency, Pantone for print
+
+### Conflict Resolution Priority
+
+When sources of truth conflict:
+
+1. **Accessibility standards** (Tier-1a): legal and ethical obligation. Non-negotiable
+2. **Platform guidelines** (Tier-1b): enforced by platform review and user expectation
+3. **Design system / Brand guidelines** (Tier-2): internal decisions
+4. **Industry principles / Heuristics** (Tier-3): guidance when no higher-tier rule applies
+
+Documentation requirement: when a higher-priority source overrides a lower-priority source, document the conflict and resolution.
+
+## SE Transfer Verification
+
+The following SE dependency patterns were evaluated for transfer to Visual Design:
+
+| SE Pattern | Visual Design Equivalent | Key Difference |
+|---|---|---|
+| Acyclic Dependencies Principle (module DAG) | Token reference direction (primitive → semantic → component, unidirectional) | SE prohibits all cycles; visual design distinguishes intentional override patterns from unintentional cycles |
+| Dependency Inversion Principle (depend on abstractions) | Token abstraction (components depend on semantic tokens, not primitive values) | SE uses interfaces; visual design uses semantic tokens as the abstraction layer |
+| Stable Dependencies Principle (depend toward stability) | Source of Truth Priority (depend toward higher-tier standards) | SE measures stability by coupling metrics; visual design measures by enforcement mechanism strength |
+| Referential Integrity (foreign keys) | Token reference integrity, design tool–code consistency | SE enforces at database level; visual design verifies at build pipeline and design review level |
+| Diamond Dependencies (version conflict) | Token conflicts (same semantic token, different primitive values in different themes) | SE resolves with version managers; visual design resolves with theme-scoped token overrides |
+
+## Related Documents
+- concepts.md — Token, component, color, typography, brand, motion term definitions
+- structure_spec.md — Token layers, component layers, state system, required relationships
+- logic_rules.md — Color/typography/accessibility/motion/brand behavioral rules
+- domain_scope.md — Normative hierarchy (Tier-1a/1b/2/3), source of truth priority mapping
+- competency_qs.md — Dependency-related verification questions (CQ-DS, CQ-SOT, CQ-CO)

package/.onto/domains/visual-design/domain_scope.md

@@ -0,0 +1,290 @@
+---
+version: 2
+last_updated: "2026-04-16"
+source: manual
+status: established
+---
+
+# Visual Design Domain — Domain Scope Definition
+
+This is the reference document used by coverage to identify "what should exist but is missing."
+This domain applies when **reviewing** visual design systems (design systems, brand identity, UI/UX visual elements, print/digital media design).
+It identifies "what should be there but is missing" based on core principles and systems of visual design.
+
+> **Boundary with ui-design domain**: ui-design covers "the structure through which the interface accommodates user intent and communicates results." This domain covers "the visual expression system" — color, typography, composition, layout, branding, iconography, motion aesthetics. Button placement, feedback timing, and disabled-state logic are ui-design's jurisdiction; button color, typeface, border-radius, and hover color shift are this domain's jurisdiction.
+
+## Key Sub-Areas
+
+Classification axis: **Visual design concern** — Classified by the design concern that the visual system must address.
+
+Applicability markers:
+- **(required)**: Must be addressed in any visual design system review. Absence indicates a fundamental gap
+- **(when applicable)**: Address when the system's feature set includes the relevant pattern. Condition type: feature existence (binary)
+- **(scale-dependent)**: Becomes required beyond a scale threshold documented per item. Condition type: scale threshold (quantitative boundary crossed)
+
+`(when applicable)` and `(scale-dependent)` are **mutually exclusive** (ME). If a concern depends on both feature presence and scale, split it into two statements.
+
+### Typography
+- **Typeface System** (required): Typeface selection rationale, typeface hierarchy (heading/body/caption/code), typeface pairing principles, fallback stacks
+- **Type Scale** (required): Size steps based on a ratio (e.g., Minor Third 1.2, Perfect Fourth 1.333), minimum/maximum size per viewport
+- **Readability** (required): Line-height per text role, measure (line length) constraints, letter-spacing rules, readability vs legibility distinction
+- **Multilingual Typography** (when applicable): CJK typesetting rules, RTL script handling, script-specific typeface fallbacks, text expansion accommodation
+- **Variable Fonts** (when applicable): Axis usage (weight, width, optical size), performance trade-offs vs multiple static files
+
+### Color
+- **Color System** (required): Color palette composition, primary/secondary/accent definition, color ratio (60-30-10), neutral palette
+- **Color Theory** (required): Color wheel relationships, harmony rules (complementary/analogous/triadic/split-complementary), color psychology by context
+- **Accessibility** (required): WCAG contrast ratio criteria (AA and AAA), color blindness accommodation, supplementary means beyond color
+- **Dark Mode/Themes** (when applicable): Light/dark theme switching via semantic tokens, elevation model inversion, image/icon adaptation per theme
+- **Data Visualization Colors** (when applicable): Sequential, diverging, and categorical palettes, colorblind-safe palette requirements
+
+### Layout and Composition
+- **Grid System** (required): Column grid (4/8/12), modular grid, gutters, margins, max-width constraints
+- **Composition Principles** (required): Visual hierarchy, Gestalt principles (proximity, similarity, continuity, closure, figure-ground), CRAP principles
+- **Spacing System** (required): Base unit (4px or 8px), spacing scale, intentional whitespace rules
+- **Responsive Layout** (required): Breakpoint definitions, fluid vs fixed widths, content reflow rules per viewport
+- **Print Layout** (when applicable): Bleed, trim, safe area, fold considerations, CMYK conversion rules
+
+### Iconography and Imagery
+- **Icon System** (required): Icon style (outline/filled/duotone), size system (16/20/24/32px), grid-based design, meaning consistency
+- **Image Usage Principles** (when applicable): Photo/illustration style guide, aspect ratios, cropping rules, image quality thresholds
+- **Data Visualization** (when applicable): Chart type selection criteria, data-ink ratio (Tufte), visual encoding principles (position, length, area, color)
+
+### Motion and Animation
+- **Motion Principles** (when applicable): Animation purpose classification (feedback/transition/guidance/decoration), easing curve system, duration system
+- **Micro-interaction Visuals** (when applicable): State transition animations (hover/active/focus), loading animations, success/error feedback animations
+- **Accessibility Motion** (required): prefers-reduced-motion support, vestibular disorder considerations, flashing content prohibition (WCAG 2.3.1)
+
+### Brand Identity
+- **Brand Visual Elements** (required): Logo usage rules (minimum size, clear space, prohibited modifications), brand colors, brand typefaces
+- **Brand Tone and Manner** (required): Visual tone definition via adjective pairs, mood boards, intended impression
+- **Medium-Specific Application** (when applicable): Print/digital/environmental graphic rules, co-branding rules, social media asset rules
+- **Brand Architecture** (scale-dependent): Sub-brand visual relationships, endorsed vs monolithic branding. Scale threshold: 2+ distinct brand identities managed
+
+### Design System
+- **Tokens** (required): Design tokens — primitive/semantic/component layers for color, typography, spacing, shadow, border-radius, z-index
+- **Components** (required): Visual specifications for reusable UI components, per-state visual representations, variant definitions
+- **Patterns** (scale-dependent): Recurring visual compositions (card layouts, hero sections, data display patterns). Scale threshold: component count >20
+- **Governance** (scale-dependent): Design system contribution/change/deprecation procedures, version management, adoption tracking. Scale threshold: 2+ contributing teams
+
+### Accessibility
+- **Visual Accessibility** (required): Contrast ratio, minimum text size, focus indicator design, information delivery means beyond color
+- **Cognitive Accessibility** (when applicable): Information overload prevention via visual hierarchy, consistent visual patterns, clear visual labeling
+- **Legal Standards** (reference): WCAG 2.1/2.2, Section 508, EN 301 549, ADA — by jurisdiction
+
+## Normative System Classification
+
+Standards governing visual design operate at four distinct tiers with different enforcement mechanisms.
+
+| Tier | Name | Enforcement Mechanism | Change Velocity | Examples |
+|------|------|----------------------|-----------------|---------|
+| Tier-1a | Accessibility Standards | **Legal obligation** + browser/AT enforcement | Slow (years) | WCAG 2.2 contrast (1.4.3, 1.4.6, 1.4.11), color-only info prohibition (1.4.1), text resize (1.4.4), flashing (2.3.1) |
+| Tier-1b | Platform Visual Standards | **OS/app store review** + device rendering constraints | Slow (years) | Apple HIG Dynamic Type, Material Design color system mandatory specs, system font rendering |
+| Tier-2 | Design System / Brand Guidelines | Design system linting/tokens, brand compliance review | Medium (quarterly) | Internal design tokens, brand style guide, component visual specs |
+| Tier-3 | Industry Principles / Heuristics | Design review, visual QA | Fast (per project) | Gestalt Principles, 60-30-10 rule, type scale ratios, 8pt grid convention |
+
+**Ordering principle**: Binding force determines priority: **Tier-1a > Tier-1b > Tier-2 > Tier-3**. When rules from different tiers conflict, the higher tier prevails.
+
+Tier classification decision tree:
+1. **Tier-1a**: Would non-conformance create an accessibility/legal violation?
+2. **Tier-1b**: If not Tier-1a, is the rule enforced by OS rendering, device constraints, or app store visual requirements?
+3. **Tier-2**: If not Tier-1a/1b, is the rule enforced by an internal design system, token system, or brand compliance process?
+4. **Tier-3**: If none of the above, treat it as an industry convention or visual design heuristic
+
+**Visual-design-specific enforcement mechanisms** (distinct from ui-design's interaction-focused mechanisms):
+- **Tier-1a**: Automated contrast checkers (axe-core, Stark), WCAG compliance audits, browser text-resize enforcement
+- **Tier-1b**: App store screenshot review, OS-level Dynamic Type / text scaling enforcement, system dark mode API
+- **Tier-2**: Design token linting (Stylelint with token rules), Figma design lint plugins, brand compliance checklists
+- **Tier-3**: Design critique sessions, visual QA by inspection, style guide adherence review — no automated enforcement
+
+### Source of Truth Priority Mapping
+
+| Existing SoT Priority (dependency_rules.md) | Tier Mapping | Rationale |
+|---------------------------------------------|-------------|-----------|
+| Accessibility standards (WCAG) | **Tier-1a** | Legal obligation + browser/AT enforcement |
+| Brand guidelines | **Tier-2** | Internal enforcement via brand review |
+| Design system documentation | **Tier-2** | Internal enforcement via token linting |
+
+### Relationship Between Tier and Abstraction Layer (L)
+
+The normative tier axis is defined here. The abstraction layer axis (`[L1]`/`[L2]`/`[L3]`) is defined in concepts.md. The two are independently defined but not all combinations are occupied:
+
+| | L1 (Standard/Specification) | L2 (Principle/Convention) | L3 (Practice/Tool-Specific) |
+|---|---|---|---|
+| **Tier-1a** | WCAG 2.2 contrast spec, color-only prohibition | WCAG interpretation guidelines | (empty) |
+| **Tier-1b** | OS font rendering specs, Dynamic Type API | Platform visual adaptation patterns | (empty) |
+| **Tier-2** | Design token specification format | Token hierarchy conventions | Team-specific token naming |
+| **Tier-3** | (empty) | Gestalt principles, color theory, type scale ratios | Project-specific visual decisions |
+
+## Cross-Cutting Concerns
+
+Cross-cutting concerns span multiple Key Sub-Areas. Defined here because their enforcement points are distributed across multiple files.
+
+Admission criteria:
+- Spans **3 or more** Key Sub-Areas
+- No single sub-area can own the concern without hiding enforcement points
+- Creates a reusable verification lens (CQ-worthy)
+
+Scale guardrail: if cross-cutting concerns exceed **Key Sub-Areas / 3**, revisit taxonomy.
+
+### Visual Consistency
+
+Identical visual concepts must have identical visual representations; deviations must be intentional and justified. Three sub-types:
+
+1. **Internal consistency** (same visual expression for the same meaning within the product):
+   - Enforcement: logic_rules.md §Constraint Conflict Checks + structure_spec.md §Required Relationships
+   - Detection: visual element inventory comparison
+
+2. **External consistency** (conformance to platform and industry visual conventions):
+   - Enforcement: domain_scope.md §Reference Standards/Frameworks + dependency_rules.md §Source of Truth Management
+   - Detection: comparison against platform guidelines and industry patterns
+
+3. **Intentional deviation with rationale requirement**: deviation must document why it provides a better outcome.
+   - Enforcement: logic_rules.md §Constraint Conflict Checks
+   - Detection: deviation audit
+
+### Accessibility Conformance
+
+Spans Color, Typography, Motion, Layout, Iconography. The visual system must meet accessibility standards across all visual elements, not just color.
+
+- Color: contrast ratios, supplementary means (structure_spec.md §Required Relationships)
+- Typography: minimum size, resize support (logic_rules.md §Typography Logic)
+- Motion: reduced-motion support (logic_rules.md §Motion Logic)
+- Layout: reflow at 200% zoom (structure_spec.md §Responsive Structure)
+- Iconography: meaning not conveyed by icon alone without text label (logic_rules.md §Accessibility Logic)
+
+## Required Concept Categories
+
+| Category | Description | Risk if Missing | Example of Failure |
+|----------|------------|----------------|-------------------|
+| Visual hierarchy | System for conveying information importance through visual means | Users cannot find critical information | Dashboard with 12 equally-sized metrics in same color; users scan randomly, miss the one KPI that requires action |
+| Color system | Rules for color selection, combination, and meaning assignment | Visual inconsistency, accessibility violations | Product uses 23 shades of blue with no defined palette; dark mode conversion produces unreadable text on 8 screens |
+| Type system | Rules for typeface, size, line-height, letter-spacing | Readability degradation, information delivery failure | Marketing site uses decorative typeface at 12px for body text; mobile bounce rate increases significantly |
+| Spacing system | Rules for distance between elements | Absence of visual rhythm, unclear relationships | Card grid uses 5 different gap values (8, 12, 15, 20, 24px); elements appear randomly placed |
+| Visual consistency | Same visual expression for the same meaning | Increased learning cost, reduced trust | "Primary" buttons are blue on 3 screens, green on 2, and purple on 1; users hesitate before clicking |
+| Accessibility | Design enabling users of diverse abilities to access visual information | User exclusion, legal violations | Error messages conveyed only by red text color; 8% of male users with red-green color blindness cannot identify errors |
+| Brand alignment | Degree to which visual elements match brand identity | Brand recognition confusion | Sub-product uses a different typeface and color palette with no documented reason; users question whether it is the same brand |
+| Source of truth | Authoritative standard for visual design decisions | Visual inconsistency proliferation | Design team and development team each maintain separate color values; 15 of 40 tokens have diverged over 6 months |
+
+## Reference Standards/Frameworks
+
+This file is the **single source of truth for external standard version information** within the visual-design domain. Other files reference standards without version numbers; the version in this table governs.
+
+| Standard/Framework | Version | Application Area | Core Content | When to Apply |
+|-------------------|---------|-----------------|--------------|---------------|
+| WCAG | 2.2 (2023) | Accessibility | Contrast ratios (1.4.3, 1.4.6, 1.4.11), color-only prohibition (1.4.1), text resize (1.4.4), flashing (2.3.1) | Every visual design review |
+| Material Design | 3 (2023) | Design system | Color system (dynamic color, tonal palettes), typography (type scale), motion (easing, duration) | Android (mandatory); others (reference) |
+| Apple HIG | 2024 | Design system | Dynamic Type, SF Symbols, vibrancy, materials, system colors, dark mode | iOS/macOS (mandatory); others (reference) |
+| Gestalt Principles | — | Composition/layout | Proximity, similarity, continuity, closure, figure-ground, common fate | Every layout/composition review |
+| Modular Scale | — | Typography | Ratio-based size step system (Minor Third 1.2, Major Third 1.25, Perfect Fourth 1.333) | Type scale definition |
+| 8pt Grid | — | Layout/spacing | 8px unit-based spacing and sizing system (4px for fine adjustments) | Spacing and layout review |
+| Color Universal Design (CUD) | — | Color/accessibility | Color design considering color vision diversity | Color palette review |
+| Atomic Design | — | Design system | Atom → Molecule → Organism → Template → Page, 5 layers | Component architecture review |
+| Design Tokens W3C | Community Group Draft (2023) | Design system | Platform-agnostic token format specification (JSON) | Token system review |
+| ICC Color Profile | v4 (2004) | Color management | sRGB, Display P3 color spaces, cross-device color consistency | Print and cross-device color review |
+
+### External-Standard Derivation Markers
+
+Rules materially derived from external standards carry grep-friendly source markers in their owner files:
+
+- `<!-- derived-from: WCAG 2.2, SC 1.4.3 -->`
+- `<!-- derived-from: Material Design 3, Color system -->`
+
+Marker usage: add when the rule would need review if the standard version changes. Keep the marker in the rule-owning file.
+
+## Bias Detection Criteria
+
+A triggered criterion indicates a review coverage problem, not necessarily a design defect.
+
+### Coverage Distribution
+
+- If 3 or more of the 8 Key Sub-Areas are not represented at all → **insufficient coverage** (threshold: ⌈8 / 2.5⌉ = 4, using 3 for visual design's tighter coupling)
+- If definitions in a specific area account for >70% of the total → **bias warning**
+
+### System Balance
+
+- If only color is defined and typography system is missing → **basic system imbalance**
+- If only components are defined and tokens are missing → **abstraction layer missing** (consistency maintenance impossible without tokens)
+- If a visual system exists without brand guidelines → **brand basis absent**
+- If only static states are defined without state transitions (hover, active, disabled) → **interaction state missing**
+
+### Media and Context
+
+- If only digital is covered while print/environmental media are applicable but missing → **media bias**
+- If only light mode is defined when dark mode is required → **theme coverage gap**
+- If only desktop visual specs exist when mobile is applicable → **viewport bias**
+
+### Governance and Authority
+
+- If 2 or more core visual elements have no designated source of truth → **authority undesignated**
+- If animation is present but no motion system or `prefers-reduced-motion` is evaluated → **animation excess without governance**
+- If design tool (Figma) and code implementation have no synchronization method defined → **tool-code drift risk**
+
+## Inter-Document Contract
+
+### Rule Ownership
+
+| Cross-cutting Topic | Owner File | Other Files |
+|---|---|---|
+| Dependency direction rules | dependency_rules.md | structure_spec.md (references only) |
+| Source of Truth priority | dependency_rules.md §Source of Truth Management | domain_scope.md (tier mapping) |
+| Concept definitions and synonyms | concepts.md | All other files reference, do not redefine |
+| Structural coherence rules | structure_spec.md §Required Relationships | Other files reference |
+| Conciseness criteria | conciseness_rules.md | Other files reference |
+| Competency questions | competency_qs.md | Other files provide inference path targets |
+| Behavioral quantitative thresholds | logic_rules.md | structure_spec.md (structural thresholds only) |
+| External-standard derivation markers | owner file of each derived rule | domain_scope.md (version SSOT only) |
+| Constraint conflict resolution | logic_rules.md §Constraint Conflict Checks | dependency_rules.md (cascading failures) |
+| Visual consistency (cross-cutting) | domain_scope.md §Cross-Cutting Concerns | logic_rules.md, structure_spec.md, dependency_rules.md |
+
+### Required Substance per Sub-area
+
+Each sub-area in Key Sub-Areas must have corresponding substance in at least one of:
+- concepts.md: term definitions
+- logic_rules.md or structure_spec.md or dependency_rules.md: operational rules
+- competency_qs.md: verification questions
+
+A sub-area with declaration but no substance in any file is a "ghost sub-area."
+
+### Cross-cutting Concern Attribution
+
+When a concern spans multiple sub-areas, attribute to the sub-area with the **primary enforcement point**:
+
+1. **Primary enforcement point**: the sub-area whose rules would be violated. Example: contrast ratio spans Color and Accessibility. Primary: Accessibility (WCAG violation is the enforcement driver)
+2. **Secondary references**: other sub-areas reference primary rules, do not duplicate
+3. **Tie-breaking**: if enforcement equally distributed, attribute to the sub-area with fewer existing items
+
+### Classification Axis Relationships
+
+| File | Axis | Facet |
+|---|---|---|
+| domain_scope.md | Visual design concern | What design concerns exist (scope) |
+| logic_rules.md | Visual construction concern | What concerns are governed by behavioral rules |
+| competency_qs.md | Verification concern | What concerns must be verified |
+
+### Sub-area to CQ Section Mapping
+
+| Sub-area | CQ Sections | Coverage |
+|---|---|---|
+| Typography | CQ-T | Full |
+| Color | CQ-C | Full |
+| Layout and Composition | CQ-GL | Full |
+| Iconography and Imagery | CQ-II | Full |
+| Motion and Animation | CQ-MO | Full |
+| Brand Identity | CQ-BI | Full |
+| Design System | CQ-DS | Full |
+| Accessibility | CQ-AC | Full |
+
+Cross-cutting CQ sections:
+- CQ-VH (Visual Hierarchy) — spans Typography, Color, Layout, Iconography
+- CQ-SOT (Source of Truth) — spans Design System, Brand Identity
+- CQ-CO (Consistency) — spans all sub-areas
+
+## Related Documents
+- concepts.md — Term definitions, abstraction layer ([L1]/[L2]/[L3]) classification
+- structure_spec.md — Visual design system structural requirements and thresholds
+- logic_rules.md — Visual construction behavioral rules, constraint conflict checks
+- dependency_rules.md — Token–component, brand–visual system, color–accessibility dependency rules
+- competency_qs.md — Verification questions organized by CQ-ID sections
+- extension_cases.md — Growth and contraction scenarios with impact analysis
+- conciseness_rules.md — Conciseness criteria for review output