AI: Update specs/css guides

Author: jlukic

ai/guides/css/tokens/architecture.md

@@ -37,7 +37,7 @@ src/css/
             ├── brand.css        # Brand color variations
             ├── layout.css       # Theme layouts
             ├── effects.css      # Theme effects
-            ├── messages.css     # Message type colors
+            ├── state-colors.css # Semantic state colors (positive/negative/info/warning)
             └── interaction.css  # Theme interactions
 ```
 

ai/guides/css/tokens/token-usage.md

@@ -43,7 +43,7 @@ src/css/
             ├── brand.css        # Brand colors
             ├── layout.css       # Layout tokens
             ├── effects.css      # Visual effects
-            ├── messages.css     # Message colors
+            ├── state-colors.css # Semantic state colors
             └── interaction.css  # Interactions
 ```
 

ai/packages/specs.md

@@ -413,12 +413,16 @@ export default {
 
 ### Usage Levels
 
-Each spec property has a `usageLevel` (1-5) that enables progressive disclosure:
-- **1**: Essential, common features shown by default
-- **2**: Frequently used variations
-- **3**: Advanced features for specific use cases
-- **4**: Specialized features for edge cases
-- **5**: Rarely used, expert-level features
+Each spec property has a `usageLevel` (1-5) that enables progressive disclosure in documentation. This follows a **descriptive linguistics approach**: combining empirical observation (what patterns exist) with editorial judgment (how frequently users will need them).
+
+Usage levels indicate how frequently users will need a feature:
+- **1**: Essential, standard features - used in most implementations (80%+ of users)
+- **2**: Common variations - frequently needed (40-80% of users)
+- **3**: Advanced features - for specific use cases (15-40% of users)
+- **4**: Specialized features - for edge cases (5-15% of users)
+- **5**: Expert-level features - rarely needed (<5% of users)
+
+Usage levels control documentation visibility (progressive disclosure) and should reflect expected usage frequency, not research adoption percentages.
 
 ## SpecReader API
 

ai/workflows/components/evaluate-research-extend-spec.md

@@ -240,9 +240,11 @@ Once decisions are finalized:
 # Include appropriate usageLevel based on our assessment
 ```
 
-**Understanding usageLevel (Progressive Disclosure)**
+**Usage Levels**
 
-The `usageLevel` property (1-5) controls how features appear in documentation through progressive disclosure. This is separate from research adoption percentages, which inform *what* to add, not *how often users will need it*.
+The `usageLevel` property (1-5) controls how features appear in documentation through progressive disclosure. This follows a **descriptive linguistics approach**: combining empirical observation (what patterns exist across frameworks) with editorial judgment (how frequently users will need them in practice).
+
+**Important**: Usage levels reflect expected usage frequency, not research adoption percentages. Research informs *what* to add; usage levels indicate *how often users will need it* in practice.
 
 **Usage Level Definitions:**