Initial commit

2025-11-30 09:02:33 +08:00
commit 0c40192593
82 changed files with 18699 additions and 0 deletions
--- a/skills/fluxwing-component-creator/docs/07-schema-reference.md
+++ b/skills/fluxwing-component-creator/docs/07-schema-reference.md
@@ -0,0 +1,205 @@
+# Schema Reference
+
+Pointer to the definitive uxscii component schema and how to use it.
+
+## The Schema File
+
+**Location**: `../schema/uxm-component.schema.json`
+
+This is the **definitive source of truth** for the uxscii `.uxm` file format.
+
+## What the Schema Defines
+
+The schema specifies:
+- All valid field names and types
+- Required vs optional fields
+- Validation rules (min/max, patterns, enums)
+- Nested object structures
+- Field descriptions
+
+## How to Use the Schema
+
+### For Reference
+
+When creating components, refer to the schema to understand:
+- What fields are available
+- What values are allowed
+- What's required vs optional
+
+### For Autocompletion
+
+Many editors can use the schema for:
+- Field suggestions
+- Type checking
+- Documentation on hover
+
+Add to your `.uxm` file:
+```json
+{
+  "$schema": "../data/schema/uxm-component.schema.json",
+  ...
+}
+```
+
+## Key Schema Sections
+
+### Required Root Fields
+
+```
+id          - Component identifier (kebab-case, 2-64 chars)
+type        - Component type (enum or "custom")
+version     - Semantic version (X.Y.Z)
+metadata    - Component metadata object
+props       - Component properties object
+ascii       - ASCII template reference
+```
+
+### Metadata Object (required fields)
+
+```
+name        - Human-readable name (1-100 chars)
+created     - ISO 8601 timestamp
+modified    - ISO 8601 timestamp
+```
+
+### Metadata Object (optional fields)
+
+```
+description - Component description (max 500 chars)
+author      - Creator name (max 100 chars)
+tags        - Array of search tags (max 10)
+category    - Component category (enum)
+```
+
+### ASCII Object (required)
+
+```
+templateFile - Template filename (must end in .md)
+width        - Character width (1-120)
+height       - Character height (1-50)
+```
+
+### ASCII Object (optional)
+
+```
+variables    - Array of template variable definitions
+```
+
+### Behavior Object (optional)
+
+```
+states       - Array of component states
+interactions - Array of user interactions
+animations   - Array of animation definitions
+accessibility- Accessibility attributes
+```
+
+## Component Types (Enum)
+
+Valid `type` values:
+```
+button, input, card, navigation, form, list, modal,
+table, badge, alert, container, text, image, divider, custom
+```
+
+## Categories (Enum)
+
+Valid `metadata.category` values:
+```
+layout, input, display, navigation, feedback,
+utility, overlay, custom
+```
+
+## Variable Types (Enum)
+
+Valid `ascii.variables[].type` values:
+```
+string, number, boolean, color, size, array, object
+```
+
+## Quick Reference Examples
+
+### Minimal Valid Component
+
+```json
+{
+  "id": "simple",
+  "type": "button",
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Simple",
+    "created": "2024-01-01T00:00:00Z",
+    "modified": "2024-01-01T00:00:00Z"
+  },
+  "props": {},
+  "ascii": {
+    "templateFile": "simple.md",
+    "width": 10,
+    "height": 3
+  }
+}
+```
+
+### Complete Component
+
+See `../examples/primary-button.uxm` for a fully-featured example using all available fields.
+
+## Schema Version
+
+Current schema version: **1.1.0**
+
+Schema follows semantic versioning:
+- Major: Breaking changes to structure
+- Minor: New optional fields
+- Patch: Documentation or validation updates
+
+## Validation Rules Summary
+
+### ID Rules
+- Pattern: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
+- Length: 2-64 characters
+- Format: kebab-case only
+
+### Version Rules
+- Pattern: `^\d+\.\d+\.\d+(?:-[a-zA-Z0-9-]+)?$`
+- Examples: `1.0.0`, `2.1.3`, `1.0.0-beta`
+
+### Timestamp Rules
+- Format: ISO 8601 date-time
+- Example: `2024-10-11T12:00:00Z`
+
+### Variable Name Rules
+- Pattern: `^[a-zA-Z][a-zA-Z0-9_]*$`
+- Format: camelCase recommended
+- Examples: `text`, `userName`, `isDisabled`
+
+## Common Schema Errors
+
+**"Additional property not allowed"**
+- You used a field name that doesn't exist in the schema
+- Check field spelling and location in object hierarchy
+
+**"Missing required property"**
+- You omitted a required field
+- Add the field with a valid value
+
+**"Value does not match pattern"**
+- Field value doesn't match regex pattern
+- Check format requirements (kebab-case, semver, etc.)
+
+**"Value not in enum"**
+- You used a value not in the allowed list
+- Use one of the valid enum values
+
+## Deep Dive
+
+For comprehensive schema documentation, see:
+- **Full guide**: `UXSCII_SCHEMA_GUIDE.md` (detailed explanations)
+- **Agent guide**: `UXSCII_AGENT_GUIDE.md` (practical examples)
+
+## Next Steps
+
+- **View schema**: Open `../schema/uxm-component.schema.json`
+- **See examples**: Browse `../examples/*.uxm`
+
+The schema ensures all uxscii components are compatible and machine-readable!