@schalkneethling/toolkit 0.2.0 → 0.4.0

package/skills/css-coder/references/patterns.md

@@ -0,0 +1,224 @@
+# CSS Patterns and Snippets
+
+This file contains reusable CSS patterns, snippets, and conventions. Consult before writing CSS.
+
+---
+
+## Utility Patterns
+
+### Visually Hidden (Screen Reader Only)
+
+Use when content should be accessible to assistive technologies but not visible on screen.
+
+```css
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+---
+
+## User Preference Queries
+
+### Reduced Motion
+
+Always wrap animations and transitions for users who prefer reduced motion.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Color Scheme
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* dark mode custom properties */
+  }
+}
+```
+
+### High Contrast
+
+```css
+@media (prefers-contrast: more) {
+  :root {
+    /* increased contrast custom properties */
+  }
+}
+```
+
+---
+
+## Color Patterns
+
+### Modern Color Syntax
+
+Always use space-separated syntax for color functions. This is the current standard and required for modern color features.
+
+```css
+/* Legacy — avoid */
+.legacy {
+  background-color: hsla(10, 100%, 50%, 0.75);
+  color: rgba(0, 0, 0, 0.9);
+}
+
+/* Modern — preferred */
+.modern {
+  background-color: hsl(10 100% 50% / 0.75);
+  color: rgb(0 0 0 / 0.9);
+}
+```
+
+Key points:
+
+- Use `rgb()` and `hsl()` — the `a` suffix (`rgba`, `hsla`) is no longer needed.
+- Separate components with spaces, not commas.
+- Use `/` before the alpha value for transparency.
+
+### Wide Gamut Colors (oklch, oklab)
+
+Use `oklch()` when users request "vibrant", "bright", or "punchy" colors. It supports a wider gamut than sRGB and is perceptually uniform, making adjustments more predictable.
+
+```css
+:root {
+  --color-accent: oklch(65% 0.25 340);
+}
+```
+
+Note: `oklch()`, `oklab()`, and `color()` only support space-separated syntax.
+
+### Relative Color Syntax
+
+Use relative colors to derive variations (hover states, overlays, tints) from existing brand variables without defining new custom properties.
+
+Syntax: `function(from [base-color] [components] / [alpha])`
+
+```css
+:root {
+  --color-brand: oklch(55% 0.2 250);
+}
+
+.button {
+  background-color: var(--color-brand);
+}
+
+.button:hover {
+  /* Lighten by adjusting the L channel */
+  background-color: oklch(from var(--color-brand) calc(l + 0.1) c h);
+}
+
+.overlay {
+  /* Apply 50% opacity to brand color */
+  background-color: oklch(from var(--color-brand) l c h / 0.5);
+}
+```
+
+---
+
+## Responsive Patterns
+
+### Shared First (Preferred over Mobile First)
+
+Avoid traditional mobile-first CSS where styles "bleed up" through open-ended `min-width` queries, requiring constant overrides. Instead, use a **Shared First** approach:
+
+1. Define only truly shared styles outside media queries.
+2. Use bounded media queries to scope styles to specific viewport ranges.
+3. Keep breakpoints to a minimum — add more only when there's a clear need.
+
+Use modern range syntax for all media queries:
+
+```css
+@media (width < 48rem) {
+  /* below breakpoint */
+}
+@media (width >= 48rem) {
+  /* at or above breakpoint */
+}
+@media (48rem <= width < 64rem) {
+  /* between breakpoints */
+}
+```
+
+**Why Shared First?**
+
+- **Fewer side effects** — Changes to one viewport don't accidentally affect others.
+- **Easier debugging** — DevTools shows fewer overridden (struck-through) properties.
+- **Clearer intent** — Each viewport's styles are self-contained.
+
+```css
+/* Mobile First — avoid */
+body {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+@media (min-width: 48rem) {
+  body {
+    flex-direction: row;
+    gap: 2rem;
+  }
+}
+```
+
+```css
+/* Shared First — preferred */
+body {
+  display: flex;
+}
+
+@media (width < 48rem) {
+  body {
+    flex-direction: column;
+    gap: 1rem;
+  }
+}
+
+@media (width >= 48rem) {
+  body {
+    flex-direction: row;
+    gap: 2rem;
+  }
+}
+```
+
+The Shared First approach may use more lines, but results in more maintainable, predictable CSS with fewer debugging headaches.
+
+#### Using Custom Properties with Shared First
+
+Custom properties can reduce repetition by keeping the property declaration shared while scoping only the value to each viewport. Use sparingly — overuse can make code harder to follow.
+
+```css
+.Dialog-container {
+  padding-block: var(--Dialog-block-padding);
+}
+
+@media (width < 48rem) {
+  .Dialog-container {
+    --Dialog-block-padding: var(--size-16);
+  }
+}
+
+@media (width >= 48rem) {
+  .Dialog-container {
+    --Dialog-block-padding: var(--size-32);
+  }
+}
+```

package/skills/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/claude-toolkit))
+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/skills/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
+
+Once confirmed, write the complete tokens file to the specified location. Use 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/skills/css-tokens/references/tokens.css

@@ -0,0 +1,162 @@
+: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: 50%;
+
+  /* ========================================
+   * 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%);
+  }
+}