sparkdesign 0.4.5 → 0.4.7

package/cli/registry/tokens/ontology.json

@@ -0,0 +1,404 @@
+{
+  "schemaVersion": "0.1.0",
+  "library": "sparkdesign",
+  "purpose": "Machine-readable design token ontology for AI agents choosing semantic styling without reading CSS internals first.",
+  "axes": {
+    "theme": {
+      "attribute": "data-theme",
+      "intent": "Controls color palette independently from layout density or geometry.",
+      "knownValues": [
+        "light",
+        "dark",
+        "light-parchment",
+        "dark-parchment"
+      ],
+      "rules": [
+        "Do not infer layout density from data-theme.",
+        "Custom themes should define --token-color-* values and rely on theme-base.css mappings.",
+        "Components should consume --color-* semantic tokens rather than raw --token-color-* internals."
+      ]
+    },
+    "style": {
+      "attribute": "data-style",
+      "intent": "Controls spacing, radius, and typography rhythm independently from color.",
+      "knownValues": [
+        "neutral",
+        "compact",
+        "soft",
+        "sharp",
+        "dense"
+      ],
+      "rules": [
+        "Use neutral when no product density preference is known.",
+        "Use compact for efficiency-oriented workspaces that need tighter controls without becoming spreadsheet-dense.",
+        "Use dense for data-heavy UI where text-sm, line-height, spacing, and radius all need compression.",
+        "Use soft for airy, approachable, reading-friendly surfaces with larger radius and more breathing room.",
+        "Use sharp when square geometry and mono-like precision are a deliberate product direction."
+      ]
+    }
+  },
+  "families": {
+    "color.primary": {
+      "tokens": [
+        "--color-primary",
+        "--color-primary-hover",
+        "--color-primary-active",
+        "--color-primary-bg",
+        "--color-primary-bg-hover",
+        "--color-primary-border",
+        "--color-primary-border-hover",
+        "--color-primary-text",
+        "--color-primary-text-hover",
+        "--color-primary-text-active",
+        "--color-text-on-primary"
+      ],
+      "intent": "Brand and primary action emphasis.",
+      "useFor": [
+        "Primary action buttons",
+        "Selected controls",
+        "Active navigation accents",
+        "Focused brand emphasis"
+      ],
+      "avoidFor": [
+        "Large page backgrounds",
+        "Destructive actions",
+        "Neutral metadata",
+        "Multiple competing actions in the same group"
+      ],
+      "agentRules": [
+        "Use only one primary action per decision surface.",
+        "Use --color-text-on-primary for text placed directly on --color-primary."
+      ]
+    },
+    "color.text": {
+      "tokens": [
+        "--color-text",
+        "--color-text-secondary",
+        "--color-text-tertiary",
+        "--color-text-quaternary",
+        "--color-text-base"
+      ],
+      "intent": "Readable hierarchy for foreground content.",
+      "useFor": [
+        "Body copy",
+        "Headings",
+        "Metadata",
+        "Disabled-looking low-emphasis support text"
+      ],
+      "avoidFor": [
+        "Status semantics that need success, warning, error, or info color",
+        "Decorative accents"
+      ],
+      "agentRules": [
+        "Use --color-text for primary readable content.",
+        "Use secondary and tertiary text only after hierarchy is established."
+      ]
+    },
+    "color.background": {
+      "tokens": [
+        "--color-bg-base",
+        "--color-bg-container",
+        "--color-bg-elevated",
+        "--color-bg-layout",
+        "--color-bg-spotlight",
+        "--color-bg-mask",
+        "--color-bg-highlight",
+        "--color-bg-highlight-hover"
+      ],
+      "intent": "Page, container, elevation, overlay, and spotlight surfaces.",
+      "useFor": [
+        "Application background",
+        "Cards and panels",
+        "Popover and modal surfaces",
+        "Overlay masks",
+        "Temporary highlight surfaces"
+      ],
+      "avoidFor": [
+        "Text foreground",
+        "Status messages without semantic color",
+        "Arbitrary decorative blocks"
+      ],
+      "agentRules": [
+        "Use --color-bg-layout for app-level backgrounds.",
+        "Use --color-bg-container or --color-bg-base for content surfaces.",
+        "Use --color-bg-mask only for modal, drawer, dialog, and popover overlays."
+      ]
+    },
+    "color.border": {
+      "tokens": [
+        "--color-border",
+        "--color-border-secondary",
+        "--color-border-tertiary",
+        "--color-input",
+        "--color-ring"
+      ],
+      "intent": "Separation, input affordance, and keyboard focus indication.",
+      "useFor": [
+        "Card and panel boundaries",
+        "Dividers",
+        "Input borders",
+        "Focus rings"
+      ],
+      "avoidFor": [
+        "Primary semantic emphasis",
+        "Replacing spacing as the only separator"
+      ],
+      "agentRules": [
+        "Use --color-ring for focus indication.",
+        "Prefer border-secondary or border-tertiary for low-emphasis separators."
+      ]
+    },
+    "color.fill": {
+      "tokens": [
+        "--color-fill",
+        "--color-fill-secondary",
+        "--color-fill-tertiary",
+        "--color-fill-quaternary",
+        "--color-fill-disable",
+        "--color-accent",
+        "--color-muted"
+      ],
+      "intent": "Subtle non-surface fills for controls, hover areas, muted chips, and disabled states.",
+      "useFor": [
+        "Hover backgrounds",
+        "Secondary controls",
+        "Muted chips",
+        "Disabled fill areas"
+      ],
+      "avoidFor": [
+        "Primary page background",
+        "High-risk status feedback",
+        "Readable foreground text"
+      ],
+      "agentRules": [
+        "Use fill tokens to support interaction affordance without adding new brand colors.",
+        "Use --color-fill-disable only when disabled semantics are explicit."
+      ]
+    },
+    "color.semantic": {
+      "tokens": [
+        "--color-link",
+        "--color-error",
+        "--color-error-hover",
+        "--color-error-bg",
+        "--color-error-bg-hover",
+        "--color-error-border",
+        "--color-info",
+        "--color-info-hover",
+        "--color-info-bg",
+        "--color-info-bg-hover",
+        "--color-info-border",
+        "--color-success",
+        "--color-success-hover",
+        "--color-success-bg",
+        "--color-success-bg-hover",
+        "--color-success-border",
+        "--color-warning",
+        "--color-warning-hover",
+        "--color-warning-bg",
+        "--color-warning-bg-hover",
+        "--color-warning-border"
+      ],
+      "intent": "Meaningful status communication.",
+      "useFor": [
+        "Validation errors",
+        "Warnings",
+        "Success confirmations",
+        "Informational callouts",
+        "Links"
+      ],
+      "avoidFor": [
+        "Pure decoration",
+        "Brand emphasis",
+        "Dense rainbow categorization without labels"
+      ],
+      "agentRules": [
+        "Do not rely on color alone; pair semantic color with text or icon labels.",
+        "Use background and border companions for Alert-like surfaces."
+      ]
+    },
+    "color.accent": {
+      "tokens": [
+        "--color-pink",
+        "--color-pink-bg",
+        "--color-pink-bg-hover",
+        "--color-purple",
+        "--color-purple-bg",
+        "--color-purple-bg-hover",
+        "--color-yellow",
+        "--color-yellow-bg",
+        "--color-yellow-bg-hover",
+        "--color-orange",
+        "--color-orange-bg",
+        "--color-orange-bg-hover",
+        "--color-teal",
+        "--color-teal-bg",
+        "--color-teal-bg-hover",
+        "--color-blue",
+        "--color-blue-bg",
+        "--color-blue-bg-hover",
+        "--color-mauve",
+        "--color-mauve-bg",
+        "--color-mauve-bg-hover",
+        "--color-slate",
+        "--color-slate-bg",
+        "--color-slate-bg-hover",
+        "--color-lavender",
+        "--color-lavender-bg",
+        "--color-lavender-bg-hover",
+        "--color-sage",
+        "--color-sage-bg",
+        "--color-sage-bg-hover"
+      ],
+      "intent": "Categorical accents for tags, files, generated artifacts, or non-status grouping.",
+      "useFor": [
+        "Category tags",
+        "File type accents",
+        "Non-critical visual grouping",
+        "Generated artifact previews"
+      ],
+      "avoidFor": [
+        "Primary actions",
+        "Error, warning, success, or info status",
+        "Long-form text"
+      ],
+      "agentRules": [
+        "Use accents sparingly and label categories explicitly.",
+        "Do not invent new accent colors in generated UI."
+      ]
+    },
+    "spacing": {
+      "tokens": [
+        "--spacing-0",
+        "--spacing-px",
+        "--spacing-0.5",
+        "--spacing-1",
+        "--spacing-1.5",
+        "--spacing-2",
+        "--spacing-2.5",
+        "--spacing-3",
+        "--spacing-3.5",
+        "--spacing-4",
+        "--spacing-5",
+        "--spacing-6",
+        "--spacing-8",
+        "--spacing-10",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24"
+      ],
+      "intent": "Rhythm and density controlled by data-style.",
+      "useFor": [
+        "Component padding",
+        "Stack gaps",
+        "Grid gutters",
+        "Inline icon-label spacing"
+      ],
+      "avoidFor": [
+        "One-off pixel nudges",
+        "Encoding visual hierarchy only through whitespace",
+        "Breaking sibling rhythm without a reason"
+      ],
+      "agentRules": [
+        "Prefer existing Tailwind spacing utilities mapped to Spark tokens.",
+        "Use larger spacing for section rhythm and smaller spacing for control internals."
+      ]
+    },
+    "radius": {
+      "tokens": [
+        "--radius-none",
+        "--radius-sm",
+        "--radius-md",
+        "--radius-lg",
+        "--radius-xl",
+        "--radius-2xl",
+        "--radius-3xl",
+        "--radius-full"
+      ],
+      "intent": "Geometry and softness controlled by data-style.",
+      "useFor": [
+        "Buttons",
+        "Cards",
+        "Inputs",
+        "Pills",
+        "Panels"
+      ],
+      "avoidFor": [
+        "Mixing unrelated radii in a single component",
+        "Using full radius for large rectangular panels",
+        "Overriding sharp or dense styles with arbitrary rounded values"
+      ],
+      "agentRules": [
+        "Let data-style drive geometry unless a component has a documented exception.",
+        "Use --radius-full only for pills, avatars, and circular controls."
+      ]
+    },
+    "typography": {
+      "tokens": [
+        "--font-size-xs",
+        "--font-size-sm",
+        "--font-size-base",
+        "--font-size-lg",
+        "--font-size-xl",
+        "--font-size-2xl",
+        "--font-size-3xl",
+        "--font-size-4xl",
+        "--font-size-5xl",
+        "--font-size-6xl",
+        "--font-size-7xl",
+        "--font-size-8xl",
+        "--font-size-9xl"
+      ],
+      "intent": "Readable type hierarchy controlled by data-style.",
+      "useFor": [
+        "Body text",
+        "Labels",
+        "Section headings",
+        "Display headings"
+      ],
+      "avoidFor": [
+        "Decorative scale jumps without information hierarchy",
+        "Tiny text for required content",
+        "Long paragraphs above base size without layout reason"
+      ],
+      "agentRules": [
+        "Use base or sm for dense application text.",
+        "Use larger sizes to express hierarchy, not decoration."
+      ]
+    },
+    "motion": {
+      "tokens": [
+        "--motion-duration-fast",
+        "--motion-duration-base",
+        "--motion-duration-slow",
+        "--motion-ease-standard",
+        "--motion-ease-emphasized",
+        "--motion-ease-out"
+      ],
+      "intent": "Purposeful feedback and state transition timing.",
+      "useFor": [
+        "Hover and press feedback",
+        "Disclosure transitions",
+        "Modal and popover entry/exit",
+        "Streaming or generation state changes"
+      ],
+      "avoidFor": [
+        "Purely decorative delay",
+        "Animating large layout shifts without user benefit",
+        "Long-running loops that distract from task work"
+      ],
+      "agentRules": [
+        "Use fast durations for control feedback.",
+        "Use base or slow only for surface transitions that clarify spatial change."
+      ]
+    }
+  },
+  "forbiddenPatterns": [
+    "Hard-coded hex colors in component className or style props.",
+    "Raw rgba overlays when --color-bg-mask or a semantic token exists.",
+    "Arbitrary radius values that fight data-style.",
+    "One-off spacing values that break sibling rhythm.",
+    "Using accent colors to communicate status without labels."
+  ]
+}

package/cli/registry/tokens/scale/presets/compact.css

@@ -1,6 +1,6 @@
 /* ============================================
  * Preset: Compact - 紧凑风格
- * 优化效率，适合信息密集场景
+ * 小幅压缩控件节奏，适合效率型工作台
  * ============================================ */
 
 [data-style="compact"] {
@@ -15,14 +15,25 @@
   --radius-2xl: 12px;
   --radius-3xl: 16px;
 
-  /* Font Size (略小) */
-  --font-size-sm: 12px;
-  --font-size-lg: 14px;
-  --font-size-xl: 16px;
+  /* Font Size (略小但保持阅读舒适) */
+  --font-size-xs: 12px;
+  --font-size-xs--line-height: 16px;
+  --font-size-sm: 13px;
+  --font-size-sm--line-height: 18px;
+  --font-size-base: 14px;
+  --font-size-base--line-height: 20px;
+  --font-size-lg: 15px;
+  --font-size-lg--line-height: 22px;
+  --font-size-xl: 17px;
+  --font-size-xl--line-height: 24px;
   --font-size-2xl: 18px;
+  --font-size-2xl--line-height: 24px;
   --font-size-3xl: 22px;
+  --font-size-3xl--line-height: 28px;
   --font-size-4xl: 28px;
+  --font-size-4xl--line-height: 32px;
   --font-size-5xl: 34px;
+  --font-size-5xl--line-height: 36px;
   --font-size-6xl: 44px;
   --font-size-7xl: 56px;
   --font-size-8xl: 64px;

package/cli/registry/tokens/scale/presets/dense.css

@@ -49,14 +49,25 @@
   /* ChatInput 特殊配置 */
   --chat-status-overlap: 4px;
 
-  /* Font Size (更小) */
-  --font-size-base: 12px;
+  /* Font Size (信息密集：主力 text-sm 也压缩) */
+  --font-size-xs: 11px;
+  --font-size-xs--line-height: 14px;
+  --font-size-sm: 12px;
+  --font-size-sm--line-height: 16px;
+  --font-size-base: 13px;
+  --font-size-base--line-height: 18px;
   --font-size-lg: 14px;
+  --font-size-lg--line-height: 20px;
   --font-size-xl: 14px;
+  --font-size-xl--line-height: 20px;
   --font-size-2xl: 16px;
+  --font-size-2xl--line-height: 22px;
   --font-size-3xl: 18px;
+  --font-size-3xl--line-height: 24px;
   --font-size-4xl: 22px;
+  --font-size-4xl--line-height: 28px;
   --font-size-5xl: 28px;
+  --font-size-5xl--line-height: 32px;
   --font-size-6xl: 36px;
   --font-size-7xl: 44px;
   --font-size-8xl: 56px;

package/cli/registry/tokens/scale/presets/sharp.css

@@ -1,12 +1,14 @@
 /* ============================================
  * Preset: Sharp - 锐利风格
- * 几何精度，无圆角 + 等宽字体
+ * 几何精度，无圆角 + 等宽字体 + 硬朗节奏
  * ============================================ */
 
 [data-style="sharp"] {
-  /* Spacing (与 compact 相同) */
+  /* Spacing (方正、克制，少量压缩) */
   --spacing-3: 10px;
   --spacing-4: 14px;
+  --spacing-5: 18px;
+  --spacing-6: 22px;
   --spacing-9: 32px;
   --spacing-11: 40px;
 
@@ -25,13 +27,23 @@
   --font-sans: var(--config-font-mono);
   font-family: var(--font-sans);
 
-  /* Font Size (与 compact 相同) */
-  --font-size-sm: 12px;
-  --font-size-lg: 14px;
-  --font-size-xl: 16px;
+  /* Font Size (工程感：略紧、等宽、层级清楚) */
+  --font-size-xs: 12px;
+  --font-size-xs--line-height: 16px;
+  --font-size-sm: 13px;
+  --font-size-sm--line-height: 18px;
+  --font-size-base: 14px;
+  --font-size-base--line-height: 20px;
+  --font-size-lg: 15px;
+  --font-size-lg--line-height: 22px;
+  --font-size-xl: 17px;
+  --font-size-xl--line-height: 24px;
   --font-size-2xl: 18px;
+  --font-size-2xl--line-height: 24px;
   --font-size-3xl: 22px;
+  --font-size-3xl--line-height: 28px;
   --font-size-4xl: 28px;
+  --font-size-4xl--line-height: 32px;
   --font-size-5xl: 34px;
   --font-size-6xl: 44px;
   --font-size-7xl: 56px;

package/cli/registry/tokens/scale/presets/soft.css

@@ -4,7 +4,17 @@
  * ============================================ */
 
 [data-style="soft"] {
-  /* 只覆盖 Radius (大圆角) */
+  /* Spacing (舒展留白) */
+  --spacing-3: 14px;
+  --spacing-4: 18px;
+  --spacing-5: 24px;
+  --spacing-6: 28px;
+  --spacing-8: 36px;
+  --spacing-9: 40px;
+  --spacing-11: 48px;
+  --spacing-12: 56px;
+
+  /* Radius (大圆角) */
   --radius-sm: 8px;
   --radius-DEFAULT: 12px;
   --radius-md: 12px;
@@ -13,4 +23,16 @@
   --radius-2xl: 24px;
   --radius-3xl: 28px;
   --radius: var(--radius-DEFAULT);
+
+  /* Font Size (阅读舒适，行高更松) */
+  --font-size-sm: 14px;
+  --font-size-sm--line-height: 22px;
+  --font-size-base: 15px;
+  --font-size-base--line-height: 24px;
+  --font-size-lg: 17px;
+  --font-size-lg--line-height: 26px;
+  --font-size-xl: 20px;
+  --font-size-xl--line-height: 28px;
+  --font-size-2xl: 22px;
+  --font-size-2xl--line-height: 30px;
 }