@schalkneethling/calavera-skill-css-tokens 0.2.0-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Schalk Neethling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/calavera-artifact.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://calavera.schalkneethling.com/schemas/calavera-artifact.schema.json",
+  "schemaVersion": 1,
+  "id": "skill-css-tokens",
+  "type": "skill",
+  "displayName": "CSS tokens",
+  "payload": "payload/css-tokens",
+  "compatibility": {
+    "calavera": ">=2.2.0 <3"
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@schalkneethling/calavera-skill-css-tokens",
+  "version": "0.2.0-next.2",
+  "description": "CSS tokens artifact for Calavera.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/schalkneethling/create-project-calavera.git",
+    "directory": "packages/artifacts/skill-css-tokens"
+  },
+  "files": [
+    "calavera-artifact.json",
+    "payload"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./calavera-artifact.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/payload/css-tokens/README.md

@@ -0,0 +1,152 @@
+# CSS Design Tokens
+
+## Quick Start
+
+1. Install the skill in your project (see [main repo README](https://github.com/schalkneethling/create-project-calavera#readme))
+2. Import `tokens.css` in your main stylesheet or HTML
+3. Start using tokens: `var(--color-primary)`, `var(--size-16)`, etc.
+
+For the philosophy and detailed usage, read on below.
+
+## Philosophy
+
+This token system embodies several key principles:
+
+### 1. Perceptual Uniformity
+
+Colors use the `oklch()` color space rather than `hsl()` or `rgb()`. This ensures:
+
+- Consistent perceived brightness across hues
+- More predictable color manipulation
+- Better accessibility through perceptual lightness control
+
+### 2. Semantic Naming
+
+Tokens are named by their purpose or scale value, not their appearance:
+
+- `--color-primary` not `--color-teal`
+- `--size-16` (16px value) not `--spacing-small`
+- `--text-xl` (size indicator) not `--heading-size`
+
+### 3. System Thinking
+
+The design system is interconnected:
+
+- Border radius values reference the spacing scale
+- Typography sizes follow a modular scale
+- Z-index uses named layers, not arbitrary numbers
+
+### 4. Dark Mode First-Class
+
+Dark mode isn't an afterthought:
+
+- Colors are redefined in `prefers-color-scheme: dark`
+- Values are adjusted for optimal contrast in both modes
+- The system maintains visual hierarchy in light and dark
+
+### 5. Scale Consistency
+
+Both spacing and typography use consistent scales:
+
+- Spacing: 4px base unit (0.25rem)
+- Typography: Modular scale with clear relationships
+
+## Token Categories
+
+### Typography
+
+- **Font Families**: System fonts with web-safe fallbacks
+- **Weights**: Named weights from regular to bold
+- **Sizes**: Modular scale from xs (12px) to 4xl (36px)
+
+### Spacing
+
+- **Size Scale**: 4px increments from 4px to 96px
+- Named by pixel value for clarity (`--size-16` = 1rem = 16px)
+
+### Colors
+
+- **Surfaces**: Background colors for different elevation levels
+- **Text**: Primary, muted, and inverted text colors
+- **Brand**: Logo-specific colors
+- **Interactive**: Primary and accent colors with hover states
+- **Semantic**: Success, error, warning, info states
+- **Borders**: Subtle and strong border options
+
+### Layout
+
+- **Border Radius**: Five levels from small to full circle
+- **Z-index**: Named layers for predictable stacking
+- **Transitions**: Three timing options (fast, base, slow)
+
+## Usage Examples
+
+```css
+/* Typography */
+.heading {
+  font-family: var(--font-family-base);
+  font-size: var(--text-2xl);
+  font-weight: var(--font-weight-bold);
+}
+
+/* Spacing */
+.card {
+  padding: var(--size-24);
+  margin-block-end: var(--size-32);
+}
+
+/* Colors */
+.button {
+  background-color: var(--color-primary);
+  color: var(--color-text-inverted);
+}
+
+.button:hover {
+  background-color: var(--color-primary-hover);
+}
+
+/* Layout */
+.modal {
+  border-radius: var(--radius-lg);
+  z-index: var(--layer-modal);
+}
+```
+
+## Customization Guide
+
+### When to Keep as-is
+
+- Working on a prototype or MVP
+- Building internal tools where brand consistency isn't critical
+- Learning design systems
+- Quick experiments or proof-of-concepts
+
+### When to Customize
+
+- Matching specific brand guidelines
+- Projects with unique visual requirements
+- Integrating with existing design systems
+- Production applications with defined visual identity
+
+**Remember**: The token _structure_ (semantic naming, scale consistency, system thinking) is more valuable than the specific values. Customize the values to fit your needs, but maintain the systematic approach.
+
+## Extending the System
+
+These tokens provide a foundation. Projects can:
+
+- Add component-specific tokens that reference these base tokens
+- Create semantic aliases (e.g., `--button-bg: var(--color-primary)`)
+- Extend the color palette while maintaining the `oklch()` approach
+- Add new token categories (shadows, animations, grid systems, etc.)
+
+The key is maintaining the system's consistency and semantic approach.
+
+## Browser Support
+
+The `oklch()` color space is supported in:
+
+- Chrome/Edge 111+
+- Safari 15.4+
+- Firefox 113+
+
+For older browsers, consider using a PostCSS plugin to generate fallback colors, or use this as a progressive enhancement where supported browsers get optimal color fidelity.

package/payload/css-tokens/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: css-tokens
+description: Provides foundational CSS design tokens (custom properties) for typography, spacing, colors, borders, z-index, and transitions. Use when setting up a base token system for a web project.
+---
+
+# CSS Design Tokens Skill
+
+## Purpose
+
+This skill provides a comprehensive set of CSS design tokens (custom properties) to establish a consistent design foundation for web projects. Use this skill when the user requests a base token system or design tokens for their CSS.
+
+## When to Use This Skill
+
+Use this skill when the user asks for:
+
+- "Add design tokens to my project"
+- "Set up CSS tokens"
+- "Create a tokens file"
+- "Add base CSS variables"
+- Similar requests for foundational CSS custom properties
+
+## When NOT to Use This Skill
+
+- User already has an existing design token system (suggest modifications instead)
+- User specifically requests a framework-specific token system (e.g., Tailwind config, CSS-in-JS tokens)
+- User only needs a subset of tokens (offer to extract specific categories)
+
+## What This Skill Provides
+
+A complete `tokens.css` file with a comprehensive design token system:
+
+- **Typography**: Font families, weights, and a modular size scale (xs to 4xl)
+- **Spacing**: Consistent size scale from 4px to 96px, named by pixel value
+- **Colors**: Using `oklch()` color space for perceptually uniform colors with light/dark mode variants for surfaces, text, brand, interactive elements, and semantic states
+- **Borders**: Radius values derived from the size scale (sm to full)
+- **Z-index**: Named layers for stacking context (dropdown, modal, toast, etc.)
+- **Transitions**: Standard timing values (fast, base, slow)
+
+Users can reference individual tokens using CSS custom property syntax: `var(--token-name)`
+
+## Token Content
+
+The complete token definitions are located in `references/tokens.css` within this skill directory. This file contains all the CSS custom property declarations organized by category.
+
+## How to Use This Skill
+
+### 1. Detect CSS Directory
+
+Search the project for common CSS directory names:
+
+- `css/`
+- `styles/`
+- `assets/css/`
+- `stylesheets/`
+- `src/css/`
+- `src/styles/`
+
+Check directories at multiple levels (root, `src/`, `public/`, `assets/`).
+
+### 2. Confirm Location with User
+
+**If a CSS directory is found:**
+
+Present the discovered location and ask for confirmation:
+
+```text
+I found a CSS directory at [path]. Should I add the design tokens to this directory in a file named `tokens.css`?
+
+If you'd like a different location or filename, please specify both.
+```
+
+**If no CSS directory is found:**
+
+Ask the user directly:
+
+```text
+I couldn't find an existing CSS directory in your project. Please specify:
+1. The directory path where you'd like the tokens file (I can create it if needed)
+2. The filename (e.g., `tokens.css`, `design-tokens.css`)
+```
+
+### 3. Write the Tokens File
+
+Before writing, check whether the target file exists. If it does, show its current content or a diff and require an explicit decision to overwrite it or choose a new file. Once that decision is confirmed, write the complete tokens file using the exact content from `references/tokens.css` in this skill directory.
+
+### 4. Inform User About Import
+
+After successfully writing the file, inform the user:
+
+✓ Design tokens written to [full-path]
+
+To use these tokens in your project, import this file in your main CSS file or HTML:
+
+**In CSS:**
+
+```css
+@import url("path/to/tokens.css");
+```
+
+**In HTML:**
+
+```html
+<link rel="stylesheet" href="path/to/tokens.css" />
+```
+
+The tokens are now available as CSS custom properties throughout your project (e.g., `var(--color-primary)`, `var(--size-16)`).
+
+## Customization
+
+These tokens provide a solid foundation but are meant to be customized for your project:
+
+- Adjust color values to match your brand
+- Modify the spacing scale to fit your design system
+- Add project-specific tokens as needed
+- Extend categories with additional tokens (animations, shadows, etc.)
+
+This is a **scaffolding skill** - it sets up the initial structure but doesn't handle ongoing modifications.
+
+## Important Notes
+
+- **Do NOT make assumptions** about directory structure or filename if the user hasn't specified
+- **Always confirm** the location before writing
+- **Create directories** if needed and confirmed by user
+- The tokens file includes both light and dark mode color schemes using `prefers-color-scheme`
+- The `oklch()` color space provides perceptually uniform colors for better accessibility and consistency

package/payload/css-tokens/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CSS Tokens"
+  short_description: "Create a foundational CSS token system."
+  default_prompt: "Use $css-tokens to add a CSS token foundation to this project."

package/payload/css-tokens/references/tokens.css

@@ -0,0 +1,158 @@
+:root {
+  /* ========================================
+   * Typography - Font Families
+   * ======================================== */
+  --font-family-base:
+    inter, "Source Sans 3", "IBM Plex Sans", -apple-system, blinkmacsystemfont, "Segoe UI", roboto,
+    helvetica, arial, sans-serif;
+  --font-family-mono:
+    ui-monospace, "SF Mono", "Cascadia Code", "Segoe UI Mono", "Liberation Mono", menlo, monaco,
+    consolas, monospace;
+
+  /* ========================================
+   * Typography - Font Weights
+   * ======================================== */
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* ========================================
+   * Typography - Font Sizes
+   * Token name = approximate pixel value
+   * ======================================== */
+  --text-xs: 0.75rem; /* 12px */
+  --text-sm: 0.875rem; /* 14px */
+  --text-base: 1rem; /* 16px */
+  --text-lg: 1.125rem; /* 18px */
+  --text-xl: 1.25rem; /* 20px */
+  --text-2xl: 1.5rem; /* 24px */
+  --text-3xl: 1.875rem; /* 30px */
+  --text-4xl: 2.25rem; /* 36px */
+
+  /* ========================================
+   * Spacing / Size Scale
+   * Token name = pixel value (--size-16 = 16px = 1rem)
+   * ======================================== */
+  --size-4: 0.25rem; /* 4px */
+  --size-8: 0.5rem; /* 8px */
+  --size-12: 0.75rem; /* 12px */
+  --size-16: 1rem; /* 16px */
+  --size-20: 1.25rem; /* 20px */
+  --size-24: 1.5rem; /* 24px */
+  --size-32: 2rem; /* 32px */
+  --size-40: 2.5rem; /* 40px */
+  --size-48: 3rem; /* 48px */
+  --size-64: 4rem; /* 64px */
+  --size-80: 5rem; /* 80px */
+  --size-96: 6rem; /* 96px */
+
+  /* ========================================
+   * Border Radius (uses size tokens)
+   * ======================================== */
+  --radius-sm: var(--size-4);
+  --radius-md: var(--size-8);
+  --radius-lg: var(--size-12);
+  --radius-xl: var(--size-16);
+  --radius-full: 9999px;
+
+  /* ========================================
+   * Z-Index Layers
+   * ======================================== */
+  --layer-send-to-back: -1;
+  --layer-dropdown: 100;
+  --layer-modal: 300;
+  --layer-toast: 400;
+  --layer-bring-to-front: 9999;
+
+  /* ========================================
+   * Transitions
+   * ======================================== */
+  --transition-fast: 150ms ease;
+  --transition-base: 250ms ease;
+  --transition-slow: 400ms ease;
+
+  /* ========================================
+   * Colors - Light Mode (Default)
+   * Using oklch() for perceptual uniformity
+   * ======================================== */
+
+  /* Surfaces */
+  --color-surface: oklch(98% 0.005 250deg); /* Near white */
+  --color-surface-raised: oklch(100% 0 0deg); /* Pure white */
+  --color-surface-sunken: oklch(95% 0.01 250deg); /* Slightly darker */
+
+  /* Text */
+  --color-text: oklch(25% 0.02 250deg); /* Dark slate */
+  --color-text-muted: oklch(50% 0.015 250deg); /* Medium gray */
+  --color-text-inverted: oklch(98% 0.005 250deg); /* Light for dark backgrounds */
+
+  /* Logo Colors - derived from brand */
+  --color-logo-maker: oklch(40% 0.025 220deg); /* Dark slate-blue */
+  --color-logo-bench: oklch(55% 0.15 185deg); /* Teal */
+
+  /* Primary - Teal (matches logo "Bench") */
+  --color-primary: oklch(50% 0.14 185deg);
+  --color-primary-hover: oklch(45% 0.14 185deg);
+  --color-primary-active: oklch(40% 0.14 185deg);
+
+  /* Accent - Coral/Orange for CTAs */
+  --color-accent: oklch(65% 0.18 35deg);
+  --color-accent-hover: oklch(60% 0.18 35deg);
+
+  /* Borders */
+  --color-border: oklch(88% 0.01 250deg);
+  --color-border-strong: oklch(75% 0.015 250deg);
+
+  /* States */
+  --color-success: oklch(55% 0.15 145deg);
+  --color-error: oklch(55% 0.2 25deg);
+  --color-warning: oklch(70% 0.15 80deg);
+  --color-info: oklch(55% 0.12 240deg);
+
+  /* Focus ring */
+  --color-focus-ring: oklch(55% 0.15 185deg / 50%);
+}
+
+/* ========================================
+ * Colors - Dark Mode
+ * ======================================== */
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Surfaces */
+    --color-surface: oklch(18% 0.015 250deg); /* Deep charcoal */
+    --color-surface-raised: oklch(22% 0.015 250deg); /* Elevated dark */
+    --color-surface-sunken: oklch(14% 0.015 250deg); /* Deeper */
+
+    /* Text */
+    --color-text: oklch(92% 0.01 250deg); /* Light gray */
+    --color-text-muted: oklch(65% 0.01 250deg); /* Muted gray */
+    --color-text-inverted: oklch(18% 0.015 250deg); /* Dark for light backgrounds */
+
+    /* Logo Colors - brighter for dark mode */
+    --color-logo-maker: oklch(75% 0.02 220deg); /* Lighter slate */
+    --color-logo-bench: oklch(65% 0.15 185deg); /* Brighter teal */
+
+    /* Primary - Brighter teal for dark mode */
+    --color-primary: oklch(60% 0.14 185deg);
+    --color-primary-hover: oklch(65% 0.14 185deg);
+    --color-primary-active: oklch(55% 0.14 185deg);
+
+    /* Accent */
+    --color-accent: oklch(70% 0.16 35deg);
+    --color-accent-hover: oklch(75% 0.16 35deg);
+
+    /* Borders */
+    --color-border: oklch(30% 0.015 250deg);
+    --color-border-strong: oklch(40% 0.015 250deg);
+
+    /* States */
+    --color-success: oklch(60% 0.15 145deg);
+    --color-error: oklch(60% 0.18 25deg);
+    --color-warning: oklch(75% 0.15 80deg);
+    --color-info: oklch(60% 0.12 240deg);
+
+    /* Focus ring */
+    --color-focus-ring: oklch(60% 0.15 185deg / 50%);
+  }
+}