devtronic 1.2.2 → 1.2.4

package/templates/addons/design-best-practices/reference/spatial-design.md

@@ -0,0 +1,161 @@
+# Spatial Design Reference
+
+Guide to spacing, layout, and visual hierarchy through spatial relationships.
+
+---
+
+## Base Unit: 4px Grid
+
+All spacing values should be multiples of 4px:
+
+```
+4px  → tight inline spacing, icon padding
+8px  → compact element spacing
+12px → related element groups
+16px → standard element spacing (1rem)
+24px → section padding, card padding
+32px → between distinct groups
+48px → section separation
+64px → major section breaks
+96px → hero/page-level spacing
+```
+
+**Why 4px:** Divisible into halves (2px for borders/outlines) and works at all scale factors. 8px is also common — pick one and be consistent.
+
+---
+
+## Spacing Hierarchy
+
+Use spacing to communicate relationships:
+
+| Relationship | Spacing | Example |
+|-------------|---------|---------|
+| Tight coupling | 4-8px | Icon + label, badge + text |
+| Related items | 12-16px | Form field + label, list items |
+| Group boundary | 24-32px | Card sections, form groups |
+| Section break | 48-64px | Page sections, content blocks |
+| Page-level | 96px+ | Hero to content, footer spacing |
+
+**Rule:** Smaller gaps = related. Larger gaps = distinct. Don't use equal spacing everywhere.
+
+---
+
+## Layout Grids
+
+### CSS Grid for Page Layout
+
+```css
+/* 12-column responsive grid */
+.layout {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: 24px;
+  max-width: 1200px;
+  margin-inline: auto;
+  padding-inline: 16px;
+}
+
+/* Content areas span columns */
+.main { grid-column: 1 / 9; }
+.sidebar { grid-column: 9 / 13; }
+
+/* Responsive collapse */
+@media (max-width: 768px) {
+  .layout { grid-template-columns: 1fr; }
+  .main, .sidebar { grid-column: 1 / -1; }
+}
+```
+
+### Container Queries
+
+Use container queries for component-level responsive design:
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+@container (min-width: 400px) {
+  .card { flex-direction: row; }
+}
+
+@container (max-width: 399px) {
+  .card { flex-direction: column; }
+}
+```
+
+---
+
+## Visual Hierarchy Through Space
+
+### Scale Contrast
+
+Pair large elements with small ones for visual interest:
+
+- Large headline + small meta text
+- Big number + small label
+- Full-width hero + narrow text column
+
+### Asymmetric Layouts
+
+Break visual monotony:
+
+```css
+/* Instead of equal columns */
+.grid-interesting {
+  display: grid;
+  grid-template-columns: 2fr 1fr; /* or 1fr 2fr */
+  gap: 32px;
+}
+```
+
+### Optical Alignment
+
+Sometimes mathematical alignment looks wrong. Adjust visually:
+
+- Text with leading whitespace (quotes, bullets) may need negative indent
+- Icons in circles need slight offset from center (visual center ≠ mathematical center)
+- Padding inside rounded containers should be slightly larger than flat ones
+- Top padding often needs to be slightly less than bottom padding for visual balance
+
+---
+
+## Max Width Constraints
+
+Prevent layouts from becoming too wide:
+
+```css
+/* Content wrapper */
+.container { max-width: 1200px; margin-inline: auto; }
+
+/* Prose content */
+.prose { max-width: 65ch; }
+
+/* Cards */
+.card { max-width: 400px; }
+
+/* Full-bleed sections break out of container */
+.full-bleed {
+  width: 100vw;
+  margin-inline: calc(50% - 50vw);
+}
+```
+
+---
+
+## Z-Index Scale
+
+Define a z-index scale to avoid conflicts:
+
+```css
+:root {
+  --z-base: 0;
+  --z-dropdown: 100;
+  --z-sticky: 200;
+  --z-overlay: 300;
+  --z-modal: 400;
+  --z-popover: 500;
+  --z-toast: 600;
+  --z-tooltip: 700;
+}
+```

package/templates/addons/design-best-practices/reference/typography.md

@@ -0,0 +1,136 @@
+# Typography Reference
+
+Comprehensive guide to typographic best practices for frontend development.
+
+---
+
+## Type Scale
+
+### Modular Scale
+
+Use a consistent ratio to generate font sizes. Common ratios:
+
+| Name | Ratio | Use Case |
+|------|-------|----------|
+| Minor Third | 1.2 | Compact UI, data-dense apps |
+| Major Third | 1.25 | General purpose, most apps |
+| Perfect Fourth | 1.333 | Editorial, marketing pages |
+| Golden Ratio | 1.618 | Display-heavy, hero sections |
+
+**Example (Major Third, base 16px):**
+```
+12px → 14px → 16px → 20px → 25px → 31px → 39px → 49px
+```
+
+### Fluid Type with `clamp()`
+
+Scale font sizes smoothly between viewport breakpoints:
+
+```css
+/* clamp(min, preferred, max) */
+h1 { font-size: clamp(2rem, 5vw + 1rem, 4rem); }
+h2 { font-size: clamp(1.5rem, 3vw + 0.75rem, 2.5rem); }
+body { font-size: clamp(1rem, 1vw + 0.75rem, 1.25rem); }
+```
+
+**Rules:**
+- Minimum must be readable (≥14px for body, ≥12px for captions)
+- Maximum prevents text from becoming absurdly large
+- Preferred value uses `vw` + a fixed base for smooth scaling
+
+---
+
+## Font Selection
+
+### System Font Stacks
+
+```css
+/* Modern system stack */
+font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+
+/* Monospace */
+font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, monospace;
+```
+
+### Web Font Performance
+
+- Limit to 2 font families maximum (display + body)
+- Load only needed weights (typically 400, 500, 700)
+- Use `font-display: swap` for body, `font-display: optional` for display
+- Subset fonts to Latin characters when possible
+- Prefer variable fonts for multiple weights
+
+---
+
+## Vertical Rhythm
+
+Maintain consistent spacing based on line height:
+
+```css
+:root {
+  --line-height-base: 1.5;    /* 24px at 16px base */
+  --rhythm: calc(1rem * var(--line-height-base)); /* 24px */
+}
+
+/* All vertical spacing is multiples of the rhythm unit */
+h1 { margin-bottom: var(--rhythm); }
+p { margin-bottom: var(--rhythm); }
+section { padding-block: calc(var(--rhythm) * 2); }
+```
+
+---
+
+## Line Length
+
+Optimal reading line length: **45-75 characters** (65ch ideal).
+
+```css
+.prose {
+  max-width: 65ch;
+}
+```
+
+For narrow containers (sidebars, cards): 35-50 characters is acceptable.
+
+---
+
+## Letter Spacing (Tracking)
+
+- **Large display text** (>32px): Tighten tracking (-0.02em to -0.04em)
+- **Body text** (14-18px): Leave at default (0)
+- **Small caps / tiny labels** (<12px): Open tracking (+0.05em to +0.1em)
+- **All-uppercase text**: Always add tracking (+0.05em minimum)
+
+```css
+.display { letter-spacing: -0.02em; }
+.label-caps { letter-spacing: 0.05em; text-transform: uppercase; }
+```
+
+---
+
+## OpenType Features
+
+Enable useful ligatures and numeric features:
+
+```css
+/* Tabular numbers for data tables */
+.data { font-variant-numeric: tabular-nums; }
+
+/* Old-style numbers for body text */
+.prose { font-variant-numeric: oldstyle-nums; }
+
+/* Common ligatures */
+body { font-variant-ligatures: common-ligatures; }
+```
+
+---
+
+## Hierarchy Checklist
+
+A well-structured page should have:
+
+1. **One dominant element** — largest text, most visual weight
+2. **Clear heading progression** — H1 > H2 > H3 (don't skip levels)
+3. **Body text contrast** — noticeably smaller/lighter than headings
+4. **Caption/meta text** — smallest, lowest contrast (but still readable)
+5. **Weight variation** — pair heavy display weights with light/regular body

package/templates/addons/design-best-practices/reference/ux-writing.md

@@ -0,0 +1,190 @@
+# UX Writing Reference
+
+Guide to interface copy: error messages, labels, CTAs, empty states, and microcopy.
+
+---
+
+## Error Messages
+
+### Structure
+
+Every error message needs three parts:
+
+1. **What happened** — Clear description of the problem
+2. **Why it happened** — Brief explanation (if helpful)
+3. **What to do** — Actionable next step
+
+### Examples
+
+```
+❌ "Error 422: Validation failed"
+✅ "This email is already registered. Try signing in instead."
+
+❌ "Something went wrong"
+✅ "We couldn't save your changes. Check your connection and try again."
+
+❌ "Invalid input"
+✅ "Password must be at least 8 characters with one number."
+```
+
+### Rules
+
+- Never blame the user ("You entered an invalid email")
+- Never use technical jargon ("Error 500", "null reference")
+- Always provide a path forward
+- Use the same tone as the rest of the UI
+- Place error messages next to the field, not in a toast or alert
+
+---
+
+## Labels & Form Copy
+
+### Input Labels
+
+- Be specific: "Work email" not "Email"
+- Use nouns, not instructions: "Full name" not "Enter your full name"
+- Don't end with a colon in modern UI (the position above the input is enough)
+
+### Placeholder Text
+
+- Use for format hints only: "jane@example.com", "MM/DD/YYYY"
+- Never use as the only label (disappears on type)
+- Use lighter color than input text
+
+### Help Text
+
+- Place below the input, before error messages
+- Keep to one line: "We'll only use this for password recovery."
+- Don't repeat the label as help text
+
+---
+
+## Buttons & CTAs
+
+### Primary Actions
+
+Use specific verbs, not generic ones:
+
+```
+❌ "Submit"     → ✅ "Create account"
+❌ "OK"         → ✅ "Save changes"
+❌ "Click here" → ✅ "Download report"
+❌ "Yes"        → ✅ "Delete project"
+```
+
+### Destructive Actions
+
+- Name the action explicitly: "Delete project" not "Delete"
+- Add confirmation context: "This will permanently delete 23 files"
+- Use red/warning styling
+- Make cancel the primary (default) action in confirmation dialogs
+
+### Button Pairs
+
+```
+✅ "Cancel" / "Save changes"       (clear contrast)
+✅ "Go back" / "Continue to payment"
+❌ "No" / "Yes"                     (ambiguous)
+❌ "Cancel" / "OK"                  (what does OK mean?)
+```
+
+---
+
+## Empty States
+
+Every empty state needs:
+
+1. **Illustration or icon** (optional but effective)
+2. **Headline** — What would be here
+3. **Description** — Why it's empty
+4. **Action** — How to fill it
+
+### Examples
+
+```
+No projects yet
+You haven't created any projects. Start with a template or from scratch.
+[Create project]
+
+No results for "flarbx"
+Try a different search term or check your filters.
+[Clear search]
+
+All caught up!
+No new notifications. We'll let you know when something needs your attention.
+```
+
+### Rules
+
+- Don't leave empty containers without explanation
+- Guide toward the most common action
+- Keep tone encouraging, not apologetic
+- Different empty states: first-time vs. filtered-to-zero vs. deleted-all
+
+---
+
+## Loading Copy
+
+### Spinner/Skeleton Text
+
+- Don't write "Loading..." everywhere
+- Be specific when possible: "Loading your projects..."
+- For long waits (>3s), add context: "Setting up your workspace. This usually takes a few seconds."
+
+### Progress States
+
+```
+Uploading 3 of 12 files...
+Almost there — analyzing your data...
+Your report is ready!
+```
+
+---
+
+## Confirmation & Success
+
+### Inline Confirmation
+
+- "Changes saved" (brief, next to the action)
+- "Email sent to jane@example.com" (specific)
+- Auto-dismiss after 3-5 seconds
+
+### Don't Over-Confirm
+
+- Saving a draft: no confirmation needed (auto-save)
+- Adding to cart: show cart count update (visual confirmation)
+- Deleting a major item: full confirmation dialog
+
+---
+
+## Tone Guidelines
+
+### Default Tone: Clear, Warm, Concise
+
+```
+✅ Professional but human
+✅ Direct without being cold
+✅ Helpful without being patronizing
+```
+
+### Scale Formality by Context
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Onboarding | Warm, encouraging | "Welcome! Let's set up your workspace." |
+| Error | Calm, helpful | "That file is too large. Try one under 10MB." |
+| Success | Brief, positive | "Project created." |
+| Destructive | Serious, clear | "This will permanently delete your account and all data." |
+| Empty state | Friendly, guiding | "No messages yet. Start a conversation!" |
+
+---
+
+## Microcopy Checklist
+
+- [ ] Every button says what it does (no generic "Submit")
+- [ ] Every empty state guides toward action
+- [ ] Error messages are actionable, not technical
+- [ ] Tooltips add information, not restate labels
+- [ ] Confirmation text matches the action severity
+- [ ] Loading states are specific when possible
+- [ ] Numbers and dates are formatted for locale

package/templates/addons/design-best-practices/rules/design-quality.md

@@ -0,0 +1,53 @@
+# Design Quality
+
+Auto-loaded rule for frontend design quality. Active during frontend file editing.
+
+---
+
+## AI Slop Detection
+
+Watch for these common AI-generated design anti-patterns:
+
+### DON'T
+
+- Generic blue/purple gradients with no design rationale
+- Excessive border-radius on everything (the "pill everything" syndrome)
+- Drop shadows on every element — creates visual noise, not depth
+- Meaningless hover animations (scale, glow) on non-interactive elements
+- Placeholder-quality copy: "Welcome to our platform", "Get started today"
+- Stock illustration style with flat characters and oversized props
+- Symmetric card grids with identical spacing — no visual hierarchy
+- Rainbow-colored dashboards with competing accent colors
+- Decorative icons that add no information
+- Equal visual weight on all elements — nothing stands out
+- Dark navy + bright purple/lime accent palette (the "SaaS 2020" look)
+- Using `opacity` to create text hierarchy instead of proper color/weight choices
+
+### DO
+
+- Build a constrained color palette: neutrals first, one intentional accent
+- Create clear typographic hierarchy: vary size, weight, and color deliberately
+- Use whitespace as a design tool — tighter for groups, generous for hero content
+- Design for real content: actual copy, realistic data, edge-case lengths
+- Apply the 60-30-10 color rule: dominant, secondary, accent
+- Test contrast ratios — WCAG AA minimum (4.5:1 body, 3:1 large text)
+- Use consistent spacing rhythm based on a 4px or 8px grid
+- Make interactive elements obviously interactive (cursor, state changes)
+- Ensure focus indicators are visible for keyboard navigation
+- Design error, empty, and loading states — not just happy paths
+- Prefer information on surfaces over boxing everything in cards
+- Vary scale and weight to create visual interest, not just grid sameness
+
+---
+
+## Quick Reference
+
+For detailed guidance, see the reference docs in the `design-harden` skill:
+
+- `reference/typography.md` — Type scales, fluid sizing, vertical rhythm
+- `reference/color-and-contrast.md` — OKLCH, WCAG contrast, functional palettes
+- `reference/spatial-design.md` — Grid systems, spacing rhythm, optical alignment
+- `reference/motion-design.md` — Easing, duration rules, reduced motion
+- `reference/interaction-design.md` — States, focus management, form patterns
+- `reference/responsive-design.md` — Breakpoints, container queries, touch targets
+- `reference/ux-writing.md` — Error copy, CTAs, empty states, microcopy

package/templates/addons/design-best-practices/skills/design-harden/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: design-harden
+description: Production hardening — text overflow, i18n, error states, accessibility, responsive, edge cases with severity report
+user-invokable: true
+---
+
+# Design Harden
+
+Systematically test UI components against real-world edge cases. Produces a severity-ranked report of issues found and fixes applied.
+
+## When to Use
+
+- Before shipping any user-facing UI
+- After implementing a new feature or page
+- During pre-release QA
+- When inheriting UI code from another team
+
+---
+
+## Process
+
+### 1. Text Overflow & Content Limits
+
+Test every text element with:
+
+- **Long content**: 200+ character strings, no spaces (e.g., long URLs, German compound words)
+- **Short content**: Single character, empty string
+- **Special characters**: Quotes, ampersands, angle brackets, emoji, RTL characters
+- **Numbers**: Large numbers (1,000,000+), negative numbers, decimals
+
+**Check for:**
+- Text clipping without ellipsis
+- Layout breaking from long strings
+- Container overflow
+- Missing `text-overflow`, `overflow`, `word-break` properties
+
+### 2. Internationalization (i18n)
+
+- **Text expansion**: German/Finnish text is 30-40% longer than English
+- **RTL layout**: Does the layout mirror correctly?
+- **CJK text**: Chinese/Japanese/Korean characters may affect line height
+- **Date/number formats**: Localized formatting
+- **Pluralization**: "1 item" vs "2 items" vs "0 items"
+
+### 3. Error States
+
+Every interactive element needs:
+
+- **Validation errors**: Inline, accessible, not just color-coded
+- **Network failures**: What happens when the API is unreachable?
+- **Empty states**: No data, no results, first-time user
+- **Partial failures**: Some items load, others fail
+- **Timeout states**: Slow network, pending responses
+
+### 4. Accessibility Audit
+
+- **Keyboard navigation**: Tab order logical? All interactive elements reachable?
+- **Focus management**: Focus trap in modals? Focus restored on close?
+- **Screen reader**: Landmarks, headings hierarchy, ARIA labels, live regions
+- **Color contrast**: WCAG AA (4.5:1 body, 3:1 large text, 3:1 UI components)
+- **Motion**: `prefers-reduced-motion` respected?
+- **Touch targets**: 44x44px minimum on mobile
+
+### 5. Responsive Testing
+
+Test at these critical widths:
+- 320px (small mobile)
+- 375px (standard mobile)
+- 768px (tablet)
+- 1024px (small desktop)
+- 1440px (standard desktop)
+- 1920px+ (large desktop)
+
+**Check for:**
+- Horizontal scroll at any viewport
+- Touch targets too small on mobile
+- Text unreadable at small sizes
+- Images not scaling
+- Navigation usability on all sizes
+
+### 6. Edge Cases
+
+- **Loading states**: Skeleton screens, spinners, progressive loading
+- **Stale data**: What shows when cached data is outdated?
+- **Concurrent actions**: Double-click submit, rapid toggle
+- **Browser back/forward**: State preserved?
+- **Deep linking**: Direct URL access to specific states
+
+---
+
+## Output Format
+
+```markdown
+## Hardening Report: [Component/Page]
+
+### Summary
+- Critical: N issues
+- Major: N issues
+- Minor: N issues
+
+### Critical (must fix before ship)
+
+| # | Category | Issue | Location | Fix |
+|---|----------|-------|----------|-----|
+| 1 | Overflow | Long text breaks card layout | `Card.tsx:34` | Add `overflow-hidden truncate` |
+| 2 | A11y | No focus indicator on buttons | `Button.tsx:12` | Add `focus-visible:ring-2` |
+
+### Major (fix soon)
+
+| # | Category | Issue | Location | Fix |
+|---|----------|-------|----------|-----|
+| 3 | Responsive | Nav overlaps content at 320px | `Nav.tsx:22` | Use hamburger below 640px |
+
+### Minor (nice to have)
+
+| # | Category | Issue | Location | Fix |
+|---|----------|-------|----------|-----|
+| 4 | i18n | Hardcoded "items" string | `List.tsx:45` | Use i18n key |
+```
+
+---
+
+## Reference Docs
+
+Detailed guidance for each area is available in the `reference/` directory:
+
+- `reference/typography.md` — Type scales, fluid sizing, vertical rhythm
+- `reference/color-and-contrast.md` — OKLCH, WCAG, functional palettes
+- `reference/spatial-design.md` — Grid, spacing rhythm, optical alignment
+- `reference/motion-design.md` — Duration, easing, reduced motion
+- `reference/interaction-design.md` — States, focus, forms, keyboard nav
+- `reference/responsive-design.md` — Breakpoints, container queries, safe areas
+- `reference/ux-writing.md` — Error messages, CTAs, empty states
+
+---
+
+## Tips
+
+- Start with critical categories (overflow, a11y) before minor ones
+- Test with real content, not "Lorem ipsum"
+- Use browser DevTools to simulate slow network, different viewports
+- Run this skill on individual components, not entire pages at once