gral-frontend-skill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gral-digital
+
+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/README.md

@@ -0,0 +1,184 @@
+# Frontend Design Skills for Claude Code
+
+A system of 18 specialized slash commands that give Claude Code deep expertise in frontend design and UI/UX engineering. Each command targets a specific aspect of interface quality — from typography and layout to performance and accessibility.
+
+These are not generic prompts. They encode opinionated, production-grade design knowledge: anti-pattern detection, AI slop avoidance, WCAG compliance, and the kind of attention to detail that separates shipped from polished.
+
+## Installation
+
+Make sure you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and Node.js installed, then run:
+
+```bash
+npx gral-frontend-skill
+```
+
+That's it. The installer copies 18 commands and 8 reference files to `~/.claude/` so they're available in every Claude Code session.
+
+### First-time project setup
+
+In any project where you want to use these skills, open Claude Code and run:
+
+```
+/user:magistero teach
+```
+
+Claude will interview you about your project's audience, brand personality, and aesthetic direction, then save a `.design-context.md` file in the project root. All other commands use this file to produce context-aware results instead of generic output.
+
+You only need to do this **once per project**. If you skip it, commands will ask you to do it first.
+
+### Project-level installation
+
+If you want the skills available only inside a specific project (instead of globally), run the installer from the project root with the `--project` flag:
+
+```bash
+npx gral-frontend-skill --project
+```
+
+This copies everything to `.claude/commands/` and `.claude/reference/` within the current directory, and automatically rewrites internal paths. Commands become available as `/project:command-name`.
+
+### Updating
+
+```bash
+npx gral-frontend-skill@latest
+```
+
+### Uninstalling
+
+```bash
+npx gral-frontend-skill --uninstall
+```
+
+---
+
+## Commands
+
+### Foundation
+
+| Command | What it does |
+|---------|-------------|
+| **magistero** | Core design skill. Contains all design principles, anti-patterns, font selection procedure, and the AI Slop Test. Modes: `teach` (setup), `craft` (full build flow), or default (design creation). |
+| **forgia** | Plans UX/UI before code. Runs a discovery interview and produces a structured design brief. |
+
+### Building
+
+| Command | What it does |
+|---------|-------------|
+| **carattere** | Typography — font choices, hierarchy, scale, weight, readability |
+| **componi** | Layout & spacing — grid, rhythm, visual hierarchy, density |
+| **tinta** | Color — strategic palette, semantic color, OKLCH, accessibility |
+| **anima** | Animation — micro-interactions, entrance choreography, easing, reduced motion |
+| **muta** | Responsive — cross-device adaptation, touch targets, breakpoints |
+| **lume** | UX writing — error messages, labels, microcopy, empty states |
+| **incanto** | Delight — personality, easter eggs, celebrations, loading states |
+| **inizia** | Onboarding — first-run experience, empty states, progressive disclosure |
+
+### Tuning
+
+| Command | What it does |
+|---------|-------------|
+| **ardore** | Amplify — make safe/boring designs more impactful and memorable |
+| **smorza** | Tone down — reduce aggressive/overstimulating designs to refined |
+| **distilla** | Simplify — strip to essence, remove unnecessary complexity |
+
+### Hardening
+
+| Command | What it does |
+|---------|-------------|
+| **affina** | Performance — loading speed, rendering, bundle size, Core Web Vitals |
+| **tempra** | Resilience — error handling, i18n, text overflow, edge cases |
+| **allinea** | Design system — realign to tokens, patterns, and standards |
+
+### Quality
+
+| Command | What it does |
+|---------|-------------|
+| **scrutinio** | Audit — scored technical report (a11y, perf, theming, responsive, anti-patterns) with P0-P3 severity |
+| **lucida** | Polish — final pass on alignment, spacing, states, transitions, code quality |
+
+---
+
+## Typical Workflows
+
+### New feature (full process)
+
+```
+/user:magistero teach     → establish design context (once per project)
+/user:forgia              → discovery interview + design brief
+/user:magistero craft     → build with visual iteration
+/user:scrutinio           → technical audit
+/user:lucida              → final polish
+```
+
+### Improve existing UI
+
+```
+/user:scrutinio           → find what's wrong (scored report)
+/user:carattere           → fix typography
+/user:componi             → fix layout/spacing
+/user:tinta               → fix color
+/user:lucida              → final polish
+```
+
+### Make it bolder / quieter
+
+```
+/user:ardore              → amplify bland designs
+/user:smorza              → tone down aggressive designs
+```
+
+### Production hardening
+
+```
+/user:tempra              → edge cases, i18n, error states
+/user:affina              → performance optimization
+/user:allinea             → design system alignment
+```
+
+---
+
+## Reference Files
+
+Commands automatically consult these when they need deeper technical material:
+
+| File | Content |
+|------|---------|
+| `typography.md` | Type scales, font pairing, OpenType features, web font loading |
+| `spatial-design.md` | Spacing systems, grid, container queries, optical adjustments |
+| `color-and-contrast.md` | OKLCH, palette construction, WCAG contrast, dark mode |
+| `motion-design.md` | Duration/easing tables, reduced motion, perceived performance |
+| `interaction-design.md` | 8 interactive states, focus rings, forms, popovers, keyboard nav |
+| `responsive-design.md` | Mobile-first, input detection, safe areas, responsive images |
+| `ux-writing.md` | Button labels, error formulas, empty states, translation |
+| `craft.md` | The full forgia→build→iterate→present workflow |
+
+---
+
+## How Commands Work Together
+
+All design commands share a dependency on **magistero**, which provides:
+
+- The **Context Gathering Protocol** — ensures design context exists before any work
+- **Design principles** — typography, color, layout, motion, interaction rules
+- **Anti-pattern detection** — the AI Slop Test and absolute bans (gradient text, side-stripe borders, glassmorphism)
+- **Font selection procedure** — a structured process to avoid training-data monoculture
+
+When you run any command, it first checks for `.design-context.md` in your project root (created by `/magistero teach`), then reads magistero's principles. This ensures consistent quality across all commands.
+
+**scrutinio** is the diagnostic command — it audits without fixing, producing a scored report that maps issues to the appropriate fix commands. Run it before and after changes to track improvement.
+
+---
+
+## Manual Installation
+
+If you prefer not to use npx, you can clone and copy manually:
+
+```bash
+git clone https://github.com/gral-digital/frontend-skill.git
+cp frontend-skill/commands/*.md ~/.claude/commands/
+mkdir -p ~/.claude/reference
+cp frontend-skill/reference/*.md ~/.claude/reference/
+```
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const COMMANDS_DIR_NAME = "commands";
+const REFERENCE_DIR_NAME = "reference";
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const CLAUDE_HOME = path.join(os.homedir(), ".claude");
+
+const COMMAND_FILES = fs.readdirSync(path.join(PACKAGE_ROOT, COMMANDS_DIR_NAME));
+const REFERENCE_FILES = fs.readdirSync(
+  path.join(PACKAGE_ROOT, REFERENCE_DIR_NAME)
+);
+
+const bold = (t) => `\x1b[1m${t}\x1b[0m`;
+const green = (t) => `\x1b[32m${t}\x1b[0m`;
+const cyan = (t) => `\x1b[36m${t}\x1b[0m`;
+const dim = (t) => `\x1b[2m${t}\x1b[0m`;
+const red = (t) => `\x1b[31m${t}\x1b[0m`;
+
+function copyFiles(srcDir, destDir, files, transform) {
+  fs.mkdirSync(destDir, { recursive: true });
+  let count = 0;
+  for (const file of files) {
+    const src = path.join(srcDir, file);
+    const dest = path.join(destDir, file);
+    if (transform) {
+      const content = fs.readFileSync(src, "utf-8");
+      fs.writeFileSync(dest, transform(content), "utf-8");
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+    count++;
+  }
+  return count;
+}
+
+function installGlobal() {
+  const commandsDest = path.join(CLAUDE_HOME, "commands");
+  const referenceDest = path.join(CLAUDE_HOME, "reference");
+
+  const cmdCount = copyFiles(
+    path.join(PACKAGE_ROOT, COMMANDS_DIR_NAME),
+    commandsDest,
+    COMMAND_FILES
+  );
+
+  const refCount = copyFiles(
+    path.join(PACKAGE_ROOT, REFERENCE_DIR_NAME),
+    referenceDest,
+    REFERENCE_FILES
+  );
+
+  console.log("");
+  console.log(green("  ✓ Installed successfully"));
+  console.log("");
+  console.log(`    ${bold(cmdCount)} commands  → ${dim(commandsDest)}`);
+  console.log(`    ${bold(refCount)} references → ${dim(referenceDest)}`);
+  console.log("");
+  console.log(
+    `  Commands are now available as ${cyan("/user:command-name")} in Claude Code.`
+  );
+  console.log("");
+  console.log(`  ${bold("Next step:")} open Claude Code in a project and run:`);
+  console.log("");
+  console.log(`    ${cyan("/user:magistero teach")}`);
+  console.log("");
+  console.log(
+    dim("  This sets up your project's design context (once per project).")
+  );
+  console.log("");
+}
+
+function installProject() {
+  const projectRoot = process.cwd();
+  const commandsDest = path.join(projectRoot, ".claude", "commands");
+  const referenceDest = path.join(projectRoot, ".claude", "reference");
+
+  const rewritePath = (content) =>
+    content.replace(/~\/\.claude\/reference\//g, ".claude/reference/");
+
+  const cmdCount = copyFiles(
+    path.join(PACKAGE_ROOT, COMMANDS_DIR_NAME),
+    commandsDest,
+    COMMAND_FILES,
+    rewritePath
+  );
+
+  const refCount = copyFiles(
+    path.join(PACKAGE_ROOT, REFERENCE_DIR_NAME),
+    referenceDest,
+    REFERENCE_FILES
+  );
+
+  console.log("");
+  console.log(green("  ✓ Installed in project"));
+  console.log("");
+  console.log(`    ${bold(cmdCount)} commands  → ${dim(commandsDest)}`);
+  console.log(`    ${bold(refCount)} references → ${dim(referenceDest)}`);
+  console.log("");
+  console.log(
+    `  Commands are available as ${cyan("/project:command-name")} when Claude Code runs in this directory.`
+  );
+  console.log("");
+  console.log(`  ${bold("Next step:")} run:`);
+  console.log("");
+  console.log(`    ${cyan("/project:magistero teach")}`);
+  console.log("");
+}
+
+function uninstall() {
+  let removed = 0;
+
+  const commandsDir = path.join(CLAUDE_HOME, "commands");
+  for (const file of COMMAND_FILES) {
+    const fp = path.join(commandsDir, file);
+    if (fs.existsSync(fp)) {
+      fs.unlinkSync(fp);
+      removed++;
+    }
+  }
+
+  const referenceDir = path.join(CLAUDE_HOME, "reference");
+  for (const file of REFERENCE_FILES) {
+    const fp = path.join(referenceDir, file);
+    if (fs.existsSync(fp)) {
+      fs.unlinkSync(fp);
+      removed++;
+    }
+  }
+
+  if (
+    fs.existsSync(referenceDir) &&
+    fs.readdirSync(referenceDir).length === 0
+  ) {
+    fs.rmdirSync(referenceDir);
+  }
+
+  console.log("");
+  if (removed > 0) {
+    console.log(green(`  ✓ Removed ${removed} files from ~/.claude/`));
+  } else {
+    console.log(dim("  Nothing to remove — skills were not installed globally."));
+  }
+  console.log("");
+}
+
+function printHelp() {
+  console.log("");
+  console.log(bold("  Frontend Design Skills for Claude Code"));
+  console.log("");
+  console.log("  Usage:");
+  console.log("");
+  console.log(
+    `    ${cyan("npx gral-frontend-skill")}            Install globally ${dim("(recommended)")}`
+  );
+  console.log(
+    `    ${cyan("npx gral-frontend-skill --project")}   Install in current project only`
+  );
+  console.log(
+    `    ${cyan("npx gral-frontend-skill --uninstall")}  Remove global installation`
+  );
+  console.log(
+    `    ${cyan("npx gral-frontend-skill --help")}       Show this help`
+  );
+  console.log("");
+}
+
+const args = process.argv.slice(2);
+const flag = args[0];
+
+if (flag === "--help" || flag === "-h") {
+  printHelp();
+} else if (flag === "--uninstall") {
+  uninstall();
+} else if (flag === "--project") {
+  installProject();
+} else if (!flag) {
+  installGlobal();
+} else {
+  console.log(red(`\n  Unknown flag: ${flag}\n`));
+  printHelp();
+  process.exit(1);
+}

package/commands/affina.md

@@ -0,0 +1,257 @@
+Identify and fix performance issues to create faster, smoother user experiences.
+
+Target: $ARGUMENTS
+
+## Assess Performance Issues
+
+Understand current performance and identify problems:
+
+1. **Measure current state**:
+   - **Core Web Vitals**: LCP, FID/INP, CLS scores
+   - **Load time**: Time to interactive, first contentful paint
+   - **Bundle size**: JavaScript, CSS, image sizes
+   - **Runtime performance**: Frame rate, memory usage, CPU usage
+   - **Network**: Request count, payload sizes, waterfall
+
+2. **Identify bottlenecks**:
+   - What's slow? (Initial load? Interactions? Animations?)
+   - What's causing it? (Large images? Expensive JavaScript? Layout thrashing?)
+   - How bad is it? (Perceivable? Annoying? Blocking?)
+   - Who's affected? (All users? Mobile only? Slow connections?)
+
+**CRITICAL**: Measure before and after. Premature optimization wastes time. Optimize what actually matters.
+
+## Optimization Strategy
+
+Create systematic improvement plan:
+
+### Loading Performance
+
+**Optimize Images**:
+- Use modern formats (WebP, AVIF)
+- Proper sizing (don't load 3000px image for 300px display)
+- Lazy loading for below-fold images
+- Responsive images (`srcset`, `picture` element)
+- Compress images (80-85% quality is usually imperceptible)
+- Use CDN for faster delivery
+
+```html
+<img
+  src="hero.webp"
+  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+  sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px"
+  loading="lazy"
+  alt="Hero image"
+/>
+```
+
+**Reduce JavaScript Bundle**:
+- Code splitting (route-based, component-based)
+- Tree shaking (remove unused code)
+- Remove unused dependencies
+- Lazy load non-critical code
+- Use dynamic imports for large components
+
+```javascript
+const HeavyChart = lazy(() => import('./HeavyChart'));
+```
+
+**Optimize CSS**:
+- Remove unused CSS
+- Critical CSS inline, rest async
+- Minimize CSS files
+- Use CSS containment for independent regions
+
+**Optimize Fonts**:
+- Use `font-display: swap` or `optional`
+- Subset fonts (only characters you need)
+- Preload critical fonts
+- Use system fonts when appropriate
+- Limit font weights loaded
+
+```css
+@font-face {
+  font-family: 'CustomFont';
+  src: url('/fonts/custom.woff2') format('woff2');
+  font-display: swap;
+  unicode-range: U+0020-007F;
+}
+```
+
+**Optimize Loading Strategy**:
+- Critical resources first (async/defer non-critical)
+- Preload critical assets
+- Prefetch likely next pages
+- Service worker for offline/caching
+- HTTP/2 or HTTP/3 for multiplexing
+
+### Rendering Performance
+
+**Avoid Layout Thrashing**:
+```javascript
+// Bad: Alternating reads and writes (causes reflows)
+elements.forEach(el => {
+  const height = el.offsetHeight;
+  el.style.height = height * 2;
+});
+
+// Good: Batch reads, then batch writes
+const heights = elements.map(el => el.offsetHeight);
+elements.forEach((el, i) => {
+  el.style.height = heights[i] * 2;
+});
+```
+
+**Optimize Rendering**:
+- Use CSS `contain` property for independent regions
+- Minimize DOM depth (flatter is faster)
+- Reduce DOM size (fewer elements)
+- Use `content-visibility: auto` for long lists
+- Virtual scrolling for very long lists (react-window, react-virtualized)
+
+**Reduce Paint & Composite**:
+- Use `transform` and `opacity` for animations (GPU-accelerated)
+- Avoid animating layout properties (width, height, top, left)
+- Use `will-change` sparingly for known expensive operations
+- Minimize paint areas (smaller is faster)
+
+### Animation Performance
+
+**GPU Acceleration**:
+```css
+/* GPU-accelerated (fast) */
+.animated {
+  transform: translateX(100px);
+  opacity: 0.5;
+}
+
+/* CPU-bound (slow) */
+.animated {
+  left: 100px;
+  width: 300px;
+}
+```
+
+**Smooth 60fps**:
+- Target 16ms per frame (60fps)
+- Use `requestAnimationFrame` for JS animations
+- Debounce/throttle scroll handlers
+- Use CSS animations when possible
+- Avoid long-running JavaScript during animations
+
+**Intersection Observer**:
+```javascript
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      // Element is visible, lazy load or animate
+    }
+  });
+});
+```
+
+### React/Framework Optimization
+
+**React-specific**:
+- Use `memo()` for expensive components
+- `useMemo()` and `useCallback()` for expensive computations
+- Virtualize long lists
+- Code split routes
+- Avoid inline function creation in render
+- Use React DevTools Profiler
+
+**Framework-agnostic**:
+- Minimize re-renders
+- Debounce expensive operations
+- Memoize computed values
+- Lazy load routes and components
+
+### Network Optimization
+
+**Reduce Requests**:
+- Combine small files
+- Use SVG sprites for icons
+- Inline small critical assets
+- Remove unused third-party scripts
+
+**Optimize APIs**:
+- Use pagination (don't load everything)
+- GraphQL to request only needed fields
+- Response compression (gzip, brotli)
+- HTTP caching headers
+- CDN for static assets
+
+**Optimize for Slow Connections**:
+- Adaptive loading based on connection (navigator.connection)
+- Optimistic UI updates
+- Request prioritization
+- Progressive enhancement
+
+## Core Web Vitals Optimization
+
+### Largest Contentful Paint (LCP < 2.5s)
+- Optimize hero images
+- Inline critical CSS
+- Preload key resources
+- Use CDN
+- Server-side rendering
+
+### First Input Delay (FID < 100ms) / INP (< 200ms)
+- Break up long tasks
+- Defer non-critical JavaScript
+- Use web workers for heavy computation
+- Reduce JavaScript execution time
+
+### Cumulative Layout Shift (CLS < 0.1)
+- Set dimensions on images and videos
+- Don't inject content above existing content
+- Use `aspect-ratio` CSS property
+- Reserve space for ads/embeds
+- Avoid animations that cause layout shifts
+
+```css
+.image-container {
+  aspect-ratio: 16 / 9;
+}
+```
+
+## Performance Monitoring
+
+**Tools to use**:
+- Chrome DevTools (Lighthouse, Performance panel)
+- WebPageTest
+- Core Web Vitals (Chrome UX Report)
+- Bundle analyzers (webpack-bundle-analyzer)
+- Performance monitoring (Sentry, DataDog, New Relic)
+
+**Key metrics**:
+- LCP, FID/INP, CLS (Core Web Vitals)
+- Time to Interactive (TTI)
+- First Contentful Paint (FCP)
+- Total Blocking Time (TBT)
+- Bundle size
+- Request count
+
+**IMPORTANT**: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative.
+
+**NEVER**:
+- Optimize without measuring (premature optimization)
+- Sacrifice accessibility for performance
+- Break functionality while optimizing
+- Use `will-change` everywhere (creates new layers, uses memory)
+- Lazy load above-fold content
+- Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)
+- Forget about mobile performance (often slower devices, slower connections)
+
+## Verify Improvements
+
+Test that optimizations worked:
+
+- **Before/after metrics**: Compare Lighthouse scores
+- **Real user monitoring**: Track improvements for real users
+- **Different devices**: Test on low-end Android, not just flagship iPhone
+- **Slow connections**: Throttle to 3G, test experience
+- **No regressions**: Ensure functionality still works
+- **User perception**: Does it *feel* faster?
+
+Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.