# CSS Format Schema — File Format Specification # KNO Schema Version: 0.5.1 # # Describes CSS (Cascading Style Sheets) as a file format. # CSS is a stylesheet language for describing the presentation of documents. # # OFFICIAL SPEC: https://www.w3.org/Style/CSS/ # CURRENT LEVEL: CSS Level 3 (modular) # # This schema enables .kno systems to understand, generate, and validate CSS. # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # BASIC TIER # ============================================================================= id: 01KGK3V73GBVRMV9N86CPA31KZ slug: css-format type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "CSS Format Schema" purpose: | Define CSS (Cascading Style Sheets) as a file format for .kno systems. **What is CSS?** CSS is a stylesheet language used to describe the presentation of documents written in HTML or XML. It is a cornerstone technology of the Web, alongside HTML and JavaScript. **Why .kno?** Understanding CSS as a format enables: - **Generation** — Convert design tokens to CSS custom properties - **Validation** — Ensure generated CSS is syntactically correct - **Transformation** — Convert between CSS and other style formats - **Documentation** — Self-describing stylesheets with provenance # ============================================================================= # RICH TIER # ============================================================================= provenance: origin: id: 01KGK3V73GBVRMV9N86CPA31KZ timestamp: "2026-02-04T01:47:56Z" tool: manual-migration taxonomy: topics: - file-formats - stylesheets - web-standards - design-systems keywords: - css - stylesheet - custom-properties - css-variables - tailwind - web relationships: extends: - xri: "kno://specs/file-format" reason: "Abstract base for all format schemas" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification" related_to: - xri: "kno://specs/style-guide-schema" reason: "Style guides produce CSS" - xri: "kno://concepts/html-format" reason: "CSS styles HTML documents" - xri: "kno://tools/tailwind" reason: "CSS framework we use" enables: - xri: "kno://capabilities/css-generation" reason: "From style guides" - xri: "kno://capabilities/theme-switching" reason: "Via CSS custom properties" - xri: "kno://capabilities/design-tokens" reason: "CSS custom properties are tokens" quality: completeness: 0.8 last_reviewed: "2026-01-09" review_status: draft _history: version: 1 created: "2026-01-09T12:00:00Z" created_by: "claude" modified: "2026-01-12T12:00:00Z" modified_by: "claude" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft changelog: - version: "0.1.0" date: "2026-01-09" changes: - "Initial CSS format schema" - "Defined CSS structure (at-rules, rulesets, declarations)" - "Documented custom properties pattern" - "Linked to W3C specifications" description: | ## CSS as a File Format CSS files have a well-defined structure: ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ CSS FILE STRUCTURE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ /* Comment */ │ │ │ │ @import "other.css"; ← At-rule (import) │ │ │ │ @theme { ← At-rule block (Tailwind v4) │ │ --color-bg: #1c1b18; ← Custom property declaration │ │ --font-serif: "Georgia"; ← Custom property declaration │ │ } │ │ │ │ .selector { ← Ruleset │ │ property: value; ← Declaration │ │ color: var(--color-bg); ← Using custom property │ │ } │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## CSS Custom Properties (CSS Variables) CSS custom properties are the bridge between design systems and CSS: ```css /* Declaration (in :root or @theme) */ --color-primary: #7a8a9e; /* Usage */ .button { background: var(--color-primary); } ``` Custom properties enable: - **Theming** — Change values at runtime - **Consistency** — Single source of truth - **Scoping** — Override in specific contexts - **Calculation** — Use in calc() expressions ## Tailwind CSS v4 Integration Tailwind v4 uses native CSS for configuration via @theme: ```css @import "tailwindcss"; @theme { --color-bg: #1c1b18; --font-serif: "Source Serif 4", Georgia, serif; } ``` This replaces the JavaScript tailwind.config.js approach with pure CSS. # =========================================================================== # CSS GRAMMAR (Simplified) # =========================================================================== grammar: description: | Simplified CSS grammar for understanding structure. Full grammar: https://www.w3.org/TR/css-syntax-3/ constructs: at_rule: description: "Rules prefixed with @ (import, media, theme, etc.)" syntax: "@identifier prelude? { block? } | @identifier prelude;" examples: - "@import 'tokens.css';" - "@theme { --color: red; }" - "@media (min-width: 768px) { ... }" ruleset: description: "Selector + declaration block" syntax: "selector-list { declaration-list }" examples: - ".button { color: red; }" - "h1, h2 { font-family: serif; }" declaration: description: "Property-value pair" syntax: "property: value;" examples: - "color: #ff0000;" - "font-size: 1rem;" custom_property: description: "CSS variable (custom property)" syntax: "--name: value;" naming: "Must start with -- (double hyphen)" usage: "var(--name) or var(--name, fallback)" examples: - "--color-primary: #7a8a9e;" - "color: var(--color-primary, blue);" comment: description: "CSS comment" syntax: "/* comment text */" note: "Can span multiple lines" # =========================================================================== # CUSTOM PROPERTY CONVENTIONS # =========================================================================== custom_property_conventions: description: | Naming conventions for CSS custom properties in design systems. namespacing: description: "Group related properties by prefix" pattern: "--{category}-{name}[-{variant}]" examples: colors: - "--color-bg" - "--color-text" - "--color-primary" - "--color-primary-hover" typography: - "--font-serif" - "--font-sans" - "--font-mono" spacing: - "--spacing-sm" - "--spacing-md" - "--spacing-lg" shadows: - "--shadow-sm" - "--shadow-md" radius: - "--radius-sm" - "--radius-md" tailwind_v4: description: "Tailwind v4 @theme variable patterns" note: "Variables in @theme become Tailwind utilities" examples: - "--color-* → bg-*, text-*, border-*" - "--font-* → font-*" - "--shadow-* → shadow-*" - "--radius-* → rounded-*" # =========================================================================== # GENERATION TEMPLATE # =========================================================================== generation: description: | Template for generating CSS from design tokens. structure: | /* ============================================================================= * GENERATED CSS TOKENS * Source: {source_file} * Generated: {timestamp} * * DO NOT EDIT MANUALLY — Edit {source_file} and regenerate. * Run: {regenerate_command} * ============================================================================= */ @theme { /* ---------------------------------------------------------------------- */ /* {SECTION_NAME} */ /* ---------------------------------------------------------------------- */ {declarations} } declaration_template: | /* {description} */ {css_variable}: {value}; # =========================================================================== # REFERENCES # =========================================================================== references: w3c_css: title: "CSS Cascading Style Sheets" url: "https://www.w3.org/Style/CSS/" description: "W3C CSS specifications home" css_syntax: title: "CSS Syntax Module Level 3" url: "https://www.w3.org/TR/css-syntax-3/" description: "Grammar and parsing rules" css_variables: title: "CSS Custom Properties for Cascading Variables" url: "https://www.w3.org/TR/css-variables-1/" description: "Custom property specification" tailwind_v4: title: "Tailwind CSS v4 Documentation" url: "https://tailwindcss.com/docs" description: "CSS-based configuration with @theme" # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 18 keywords: [id, type, version, css-format] - path: "spec/syntax" line: 100 keywords: [selectors, declarations, at-rules, comments] - path: "spec/custom_properties" line: 160 keywords: [css-variables, custom-properties, var, fallback] - path: "spec/generation" line: 220 keywords: [templates, tokens, design-system, tailwind] - path: "references" line: 270 keywords: [w3c, css-syntax, css-variables, tailwind] contains: - xri: "#identity" role: section title: "Format Metadata" keywords: [id, type, version] - xri: "#spec" role: section title: "CSS Specification" keywords: [syntax, properties, generation] - xri: "#references" role: section title: "External References" keywords: [w3c, tailwind, documentation]