@schalkneethling/toolkit 0.1.5 → 0.3.0

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%);
+  }
+}

package/skills/frontend-security/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: frontend-security
+description: Audit frontend codebases for security vulnerabilities and bad practices. Use when performing security reviews, auditing code for XSS/CSRF/DOM vulnerabilities, checking Content Security Policy configurations, validating input handling, reviewing file upload security, or examining Node.js/NPM dependencies. Target frameworks include web platform (vanilla HTML/CSS/JS), React, Astro, Twig templates, Node.js, and Bun. Based on OWASP security guidelines.
+---
+
+# Frontend Security Audit Skill
+
+Perform comprehensive security audits of frontend codebases to identify vulnerabilities, bad practices, and missing protections.
+
+## Audit Process
+
+1. **Scan for dangerous patterns** - Search codebase for known vulnerability indicators
+2. **Review framework-specific risks** - Check for framework security bypass patterns
+3. **Validate defensive measures** - Verify CSP, CSRF tokens, input validation
+4. **Check dependencies** - Review npm/node dependencies for vulnerabilities
+5. **Report findings** - Categorize by severity with remediation guidance
+
+## Critical Vulnerability Patterns to Search
+
+### XSS Indicators (Search Priority: HIGH)
+
+```bash
+# React dangerous patterns
+grep -rn "dangerouslySetInnerHTML" --include="*.jsx" --include="*.tsx" --include="*.js"
+
+# Direct DOM manipulation
+grep -rn "\.innerHTML\s*=" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
+grep -rn "\.outerHTML\s*=" --include="*.js" --include="*.ts"
+grep -rn "document\.write" --include="*.js" --include="*.ts"
+
+# URL-based injection
+grep -rn "location\.href\s*=" --include="*.js" --include="*.ts"
+grep -rn "location\.replace" --include="*.js" --include="*.ts"
+grep -rn "window\.open" --include="*.js" --include="*.ts"
+
+# Eval and code execution
+grep -rn "eval\s*(" --include="*.js" --include="*.ts"
+grep -rn "new Function\s*(" --include="*.js" --include="*.ts"
+grep -rn "setTimeout\s*(\s*['\"]" --include="*.js" --include="*.ts"
+grep -rn "setInterval\s*(\s*['\"]" --include="*.js" --include="*.ts"
+
+# Twig unescaped output
+grep -rn "|raw" --include="*.twig" --include="*.html.twig"
+grep -rn "{% autoescape false %}" --include="*.twig"
+```
+
+### CSRF Indicators
+
+```bash
+# Forms without CSRF tokens
+grep -rn "<form" --include="*.html" --include="*.jsx" --include="*.tsx" --include="*.twig"
+
+# State-changing requests without protection
+grep -rn "fetch\s*(" --include="*.js" --include="*.ts" | grep -E "(POST|PUT|DELETE|PATCH)"
+grep -rn "axios\.(post|put|delete|patch)" --include="*.js" --include="*.ts"
+```
+
+### Sensitive Data Exposure
+
+```bash
+# localStorage/sessionStorage with sensitive data
+grep -rn "localStorage\." --include="*.js" --include="*.ts"
+grep -rn "sessionStorage\." --include="*.js" --include="*.ts"
+
+# Hardcoded secrets
+grep -rn "api[_-]?key\s*[:=]" --include="*.js" --include="*.ts" --include="*.env"
+grep -rn "secret\s*[:=]" --include="*.js" --include="*.ts"
+grep -rn "password\s*[:=]" --include="*.js" --include="*.ts"
+```
+
+## Reference Documentation
+
+Load these references based on findings:
+
+- **XSS vulnerabilities found**: See `references/xss-prevention.md`
+- **CSRF concerns**: See `references/csrf-protection.md`
+- **DOM manipulation issues**: See `references/dom-security.md`
+- **CSP review needed**: See `references/csp-configuration.md`
+- **Input handling issues**: See `references/input-validation.md`
+- **Node.js/NPM audit**: See `references/nodejs-npm-security.md`
+- **Framework-specific patterns**: See `references/framework-patterns.md`
+- **File upload handling**: See `references/file-upload-security.md`
+- **JWT implementation**: See `references/jwt-security.md`
+
+## Severity Classification
+
+**CRITICAL** - Exploitable XSS, authentication bypass, secrets exposure
+**HIGH** - Missing CSRF protection, unsafe DOM manipulation, SQL injection vectors
+**MEDIUM** - Weak CSP, missing security headers, improper input validation
+**LOW** - Informational disclosure, deprecated functions, suboptimal practices
+
+## Report Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: X findings
+- High: X findings
+- Medium: X findings
+- Low: X findings
+
+### Critical Findings
+
+#### [CRITICAL-001] Title
+- **Location**: file:line
+- **Pattern**: Code snippet
+- **Risk**: Description of the vulnerability
+- **Remediation**: How to fix
+- **Reference**: OWASP link
+
+### High Findings
+[...]
+```
+
+## OWASP Reference Links
+
+For comprehensive guidance, consult these OWASP cheatsheets directly:
+
+- XSS Prevention: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
+- DOM XSS Prevention: https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html
+- CSRF Prevention: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
+- CSP: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html
+- Input Validation: https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
+- HTML5 Security: https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html
+- DOM Clobbering: https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html
+- Node.js Security: https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
+- NPM Security: https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html
+- AJAX Security: https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html
+- File Upload: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
+- Error Handling: https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html
+- JWT Security: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html
+- User Privacy: https://cheatsheetseries.owasp.org/cheatsheets/User_Privacy_Protection_Cheat_Sheet.html
+- gRPC Security: https://cheatsheetseries.owasp.org/cheatsheets/gRPC_Security_Cheat_Sheet.html