aiox-core 5.0.1 → 5.0.3

package/pro/squads/design/tasks/audit-reading-experience.md

@@ -0,0 +1,350 @@
+# Task: Audit Reading Experience
+
+> Command: `*reading-audit [path]`
+> Purpose: Audit reading components against high-retention best practices
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `standalone`
+
+## Overview
+
+This task analyzes reading-focused components (articles, blog posts, documentation, book readers) against evidence-based best practices from publishers and research.
+
+## Prerequisites
+
+- Read: `squads/super-agentes/data/high-retention-reading-guide.md`
+- Read: `squads/super-agentes/checklists/reading-accessibility-checklist.md`
+- Target path to audit
+
+## Execution Steps
+
+### Step 1: Identify Reading Components
+
+```bash
+# Find components with reading-related names
+find {path}/ -name "*.tsx" | xargs grep -l \
+  "article\|reader\|prose\|content\|blog\|post\|chapter\|book" | head -20
+
+# Find components with reading-related classes
+grep -rn --include="*.tsx" \
+  "prose\|article\|reading\|content-area\|text-container" {path}/
+```
+
+### Step 2: Typography Audit
+
+**Font Size Check:**
+```bash
+# Find font-size declarations
+grep -rn --include="*.tsx" --include="*.css" "font-size:" {path}/ \
+  | grep -E "[0-9]+px" > /tmp/font-sizes.txt
+
+# Flag sizes below 16px (excluding xs, caption, footnote)
+cat /tmp/font-sizes.txt | grep -E "1[0-5]px|[0-9]px"
+```
+
+**Expected:**
+- Body text: ≥16px (ideal 18-21px)
+- Captions: ≥11px
+- Labels: ≥13px
+
+**Line Height Check:**
+```bash
+# Find line-height declarations
+grep -rn --include="*.tsx" --include="*.css" "line-height:" {path}/ \
+  > /tmp/line-heights.txt
+
+# Flag low line-heights for body text
+cat /tmp/line-heights.txt | grep -E "1\.[0-4]|: 1[^.]"
+```
+
+**Expected:**
+- Body text: ≥1.5 (ideal 1.6)
+- Headings: 1.25-1.375
+
+**Line Length Check:**
+```bash
+# Find max-width on text containers
+grep -rn --include="*.tsx" --include="*.css" \
+  "max-width:\|measure\|ch\|prose" {path}/
+```
+
+**Expected:**
+- Body text: 50-75ch (65ch ideal)
+- Maximum: 80ch (WCAG)
+
+### Step 3: Color & Contrast Audit
+
+**Background Colors:**
+```bash
+# Find background colors
+grep -rn --include="*.tsx" --include="*.css" \
+  "background\|bg-\[#\|bg-white\|bg-black" {path}/
+
+# Flag pure white/black
+grep -rn "#FFFFFF\|#000000\|bg-white\|bg-black" {path}/ --include="*.tsx"
+```
+
+**Violations:**
+- Light mode: #FFFFFF (should be #FAFAFA-#F5F5F5)
+- Dark mode: #000000 (should be #121212-#1E1E1E)
+- Dark mode: #FFFFFF text (should be #E0E0E0)
+
+**Link Distinguishability:**
+```bash
+# Check if links have more than just color
+grep -rn --include="*.tsx" \
+  "text-blue\|text-primary\|text-link" {path}/ \
+  | grep -v "underline\|font-medium\|font-semibold"
+```
+
+**Expected:**
+- Links should have underline OR weight OR icon, not just color
+
+### Step 4: Accessibility Features Check
+
+**Theme Options:**
+```bash
+# Check for theme toggle/support
+grep -rn --include="*.tsx" \
+  "dark\|light\|sepia\|theme\|prefers-color-scheme" {path}/
+```
+
+**Expected:**
+- ≥2 themes available (light/dark minimum)
+- Sépia ideal for long reading
+
+**Reduced Motion:**
+```bash
+# Check for reduced motion support
+grep -rn "prefers-reduced-motion" {path}/ --include="*.tsx" --include="*.css"
+```
+
+**Expected:**
+- Animations respect prefers-reduced-motion
+
+**Skip Links:**
+```bash
+# Check for skip links
+grep -rn "skip\|main-content\|#content" {path}/ --include="*.tsx"
+```
+
+### Step 5: Reading UX Features
+
+**Progress Indicator:**
+```bash
+# Check for progress bar/indicator
+grep -rn --include="*.tsx" \
+  "progress\|scroll.*depth\|reading.*time\|position.*indicator" {path}/
+```
+
+**Expected:**
+- Progress bar/indicator for long content
+- Impact: +15-25% completion rate
+
+**Reading Time:**
+```bash
+# Check for reading time display
+grep -rn --include="*.tsx" \
+  "reading.*time\|min.*read\|time.*read\|word.*count" {path}/
+```
+
+**Expected:**
+- Reading time for articles >500 words
+- Format: "X min de leitura"
+
+**Save Position:**
+```bash
+# Check for position saving
+grep -rn --include="*.tsx" \
+  "bookmark\|save.*position\|continue.*reading\|last.*read" {path}/
+```
+
+### Step 6: Editorial Structure Check
+
+For content files, analyze:
+
+**Paragraph Length:**
+```bash
+# Find long text blocks
+grep -rn --include="*.tsx" "<p>" {path}/ | head -20
+```
+
+**Guidance:**
+- Ideal: 3-4 sentences per paragraph
+- Maximum: 5 sentences
+- Impact: +30% engagement
+
+**Heading Frequency:**
+```bash
+# Check heading tags
+grep -rn --include="*.tsx" "<h[1-6]" {path}/ | wc -l
+```
+
+**Guidance:**
+- Heading every 3-5 paragraphs
+- Impact: +20% navigation
+
+### Step 7: Generate Audit Report
+
+```markdown
+# Reading Experience Audit Report
+Generated: {timestamp}
+Path: {path}
+
+## Summary
+
+| Category | Score | Issues | Status |
+|----------|-------|--------|--------|
+| Typography | {score}/30 | {count} | {status} |
+| Color/Contrast | {score}/25 | {count} | {status} |
+| Accessibility | {score}/25 | {count} | {status} |
+| Reading UX | {score}/20 | {count} | {status} |
+| **Total** | **{total}/100** | **{total_issues}** | **{overall}** |
+
+## Typography ({score}/30)
+
+### Font Sizes
+| Location | Current | Expected | Status |
+|----------|---------|----------|--------|
+| Body text | 14px | ≥16px | ❌ |
+| Captions | 11px | ≥11px | ✅ |
+
+### Line Heights
+| Location | Current | Expected | Status |
+|----------|---------|----------|--------|
+| Body text | 1.4 | ≥1.5 | ❌ |
+| Headings | 1.25 | 1.25-1.375 | ✅ |
+
+### Line Length
+| Container | Current | Expected | Status |
+|-----------|---------|----------|--------|
+| Article | 100% | 65ch | ❌ |
+
+## Color & Contrast ({score}/25)
+
+### Theme Support
+| Theme | Available | Status |
+|-------|-----------|--------|
+| Light | ✅ | ✅ |
+| Dark | ❌ | ❌ Missing |
+| Sépia | ❌ | ⚠️ Recommended |
+
+### Contrast Issues
+| Element | Foreground | Background | Ratio | Required | Status |
+|---------|------------|------------|-------|----------|--------|
+| Body text | #757575 | #FFFFFF | 4.6:1 | 4.5:1 | ✅ |
+| Muted text | #9E9E9E | #FFFFFF | 2.8:1 | 4.5:1 | ❌ |
+
+### Pure White/Black Usage
+| File | Line | Issue | Fix |
+|------|------|-------|-----|
+| Reader.tsx | 45 | bg-black in dark mode | Use #121212 |
+| Article.tsx | 23 | text-white | Use #E0E0E0 |
+
+## Accessibility ({score}/25)
+
+### Features
+| Feature | Implemented | Status |
+|---------|-------------|--------|
+| Reduced motion | ❌ | ❌ Add |
+| Skip links | ❌ | ❌ Add |
+| Keyboard nav | ✅ | ✅ |
+| Focus visible | ✅ | ✅ |
+| Zoom 200% | ❌ | ❌ Test |
+
+### Link Distinguishability
+| Location | Method | Status |
+|----------|--------|--------|
+| Article body | Color only | ❌ Add underline |
+| Navigation | Color + weight | ✅ |
+
+## Reading UX ({score}/20)
+
+### Features
+| Feature | Implemented | Impact |
+|---------|-------------|--------|
+| Progress bar | ❌ | +15-25% completion |
+| Reading time | ❌ | +10% starts |
+| Save position | ❌ | +retention |
+| Highlights | ❌ | +20% return |
+
+## Recommendations
+
+### Critical (Fix Immediately)
+1. Increase body font size from 14px to 18px
+2. Add dark mode with #121212 background
+3. Limit line length to 65ch
+
+### High Priority
+4. Add progress bar indicator
+5. Add reading time estimate
+6. Replace pure white/black in dark mode
+
+### Medium Priority
+7. Add sépia theme option
+8. Implement position saving
+9. Add reduced motion support
+
+### Nice to Have
+10. Add highlight functionality
+11. Add annotation support
+
+## Comparison with Publishers
+
+| Metric | Current | Medium | NYT | Target |
+|--------|---------|--------|-----|--------|
+| Font size | 14px | 21px | 18px | 18px |
+| Line height | 1.4 | 1.58 | 1.5 | 1.6 |
+| Max width | 100% | 680px | 600px | 65ch |
+| Progress bar | ❌ | ✅ | ❌ | ✅ |
+| Dark mode | ❌ | ✅ | ✅ | ✅ |
+
+## Estimated Impact
+
+| Change | Expected Impact |
+|--------|-----------------|
+| Font 14→18px | +5-10% reading speed |
+| Line height 1.4→1.6 | +10% completion |
+| Progress bar | +15-25% completion |
+| Dark mode proper | Avoid -14% comprehension |
+| Shorter paragraphs | +30% engagement |
+```
+
+## Output Location
+
+```
+outputs/design-system/{project}/
+├── reading-audit-{date}.md
+├── reading-metrics.json
+└── reading-recommendations.md
+```
+
+## Failure Handling
+
+- **Reading components not identifiable:** Expand search patterns to include generic container names (ContentArea, TextBlock, Article), manually inspect top-level page components, request user to specify reading-focused routes
+- **Typography values computed dynamically:** Extract CSS variables and Tailwind config, trace token references, run browser DevTools inspection to capture computed values, document dynamic calculation logic
+- **Contrast ratios fail across all themes:** Generate color palette overhaul proposal with WCAG-compliant alternatives maintaining brand proximity, calculate perceptual difference (ΔE), prioritize high-traffic components for immediate fixes
+- **Progress/reading-time features missing across entire codebase:** Provide implementation templates (React hooks, vanilla JS), estimate implementation effort per component type, include analytics integration for measuring completion rate impact
+
+## Success Criteria
+
+- [ ] All reading components identified
+- [ ] Typography metrics collected
+- [ ] Contrast ratios validated
+- [ ] Accessibility features checked
+- [ ] Reading UX features inventoried
+- [ ] Report with prioritized recommendations
+
+## Related Commands
+
+- `*ds-health` - Overall DS health
+- `*validate-tokens` - Token usage validation
+- `*contrast-check` - Detailed contrast analysis
+- `*reading-tokens` - Generate reading-specific tokens
+
+
+## Related Checklists
+
+- `squads/design/checklists/reading-accessibility-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/audit-tailwind-config.md

@@ -0,0 +1,101 @@
+# Audit Tailwind v4 Configuration & Utility Health
+
+> Task ID: brad-audit-tailwind-config  
+> Agent: Brad (Design System Architect)  
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `modernization`
+
+## Description
+
+Review Tailwind CSS v4 setup to guarantee @theme layering, content scanning, utility hygiene, and performance baselines are correct. Produces remediation plan and metrics.
+
+## Prerequisites
+
+- Tailwind v4 installed (or upgrade plan underway)
+- Access to codebase for static analysis
+- Ability to run Tailwind build locally
+
+## Workflow
+
+1. **Collect Context**
+   - Locate primary CSS entry (`app.css`, `src/styles.css`, etc.)
+   - Identify additional `@imports`, custom utilities, plugins
+   - Read `.state.yaml` for current Tailwind metadata (if available)
+
+2. **Validate @theme Layers**
+   - Ensure tokens defined within `@theme` grouped as core → semantic → component
+   - Confirm dark mode overrides (`[data-theme="dark"]`) map to semantic tokens
+   - Check no residual `theme.extend` references exist
+
+3. **Inspect @layer Usage**
+   - `@layer base`: Resets, typography, `focus-visible`
+   - `@layer components`: Reusable abstractions (e.g., `.form-label`)
+   - `@layer utilities`: Custom utility definitions with `@utility`
+   - Verify ordering (base → components → utilities) and duplication avoidance
+
+4. **Content & Purge Coverage**
+   - Review Tailwind CLI entry for `content` globs (JIT purge)
+   - Ensure glob coverage includes `.tsx`, `.jsx`, `.mdx`, Storybook stories, templates
+   - Flag false negatives (classes generated dynamically) and propose safelist
+
+5. **Utility Health Scan**
+   - Run class collision detection (tailwind-merge or eslint-plugin-tailwindcss)
+   - Identify redundant custom utilities replaced by tokens/variants
+   - Detect legacy classes (e.g., `outline-none` instead of `outline-hidden`)
+
+6. **Performance Snapshot**
+   - Record build metrics (cold + incremental)
+   - Capture CSS bundle size, number of utilities generated
+   - Compare with target benchmarks (Oxide reference)
+
+7. **Report & Remediation**
+   - Summarize findings (pass/warn/fail) in `docs/reports/tailwind-audit.md`
+   - Provide prioritized action list (tokens to add, utilities to remove, config fixes)
+   - Update `.state.yaml` with audit timestamp, benchmark data, outstanding actions
+
+## Output
+
+- Audit report (`docs/reports/tailwind-audit.md`)
+- Updated `.state.yaml` under `tooling.tailwind` (validation + metrics)
+- Optional lint/config patches (ESLint Tailwind rules, Prettier plugin settings)
+
+## Failure Handling
+
+- **@theme layer structure invalid or missing:** Abort audit, provide migration guide from theme.extend to @theme syntax, generate conversion script for existing token files, require manual review before re-running
+- **Content glob paths exclude significant template files:** Analyze build output for unpurged classes, cross-reference with file structure to identify missing patterns, update content config with discovered paths, validate with test build
+- **Tailwind-merge reports >50 class conflicts:** Generate conflict resolution report grouping by conflict type (responsive collisions, arbitrary value conflicts), provide automated cva refactoring suggestions, prioritize by usage frequency
+- **Build performance degrades >30% vs baseline:** Profile build with --debug flag, identify slow plugins or @layer definitions, recommend selective imports or JIT optimizations, consider splitting config for multi-app monorepos
+
+## Success Criteria
+
+- [ ] `@theme` defines full token stack with no missing categories
+- [ ] `@layer` usage consistent and free of duplicate definitions
+- [ ] Content paths cover 100% of templates (no orphaned utilities)
+- [ ] tailwind-merge/eslint scans zero conflicts or all logged issues resolved
+- [ ] Build metrics captured (cold/incremental) and comparable to prior baseline
+- [ ] Recommendations documented with owners + due dates
+- [ ] `.state.yaml` updated (`tailwind_theme_validated: true/false`) and audit timestamp logged
+
+## Tools & Commands
+
+- Tailwind CLI build: `npx tailwindcss -i ./app.css -o ./dist.css --watch`
+- Utility audit: `npx @tailwindcss/oxide --analyze`
+- ESLint Tailwind plugin: `eslint --ext .tsx src`
+- tailwind-merge checker: integrate via ESLint rule `tailwindcss/no-contradicting-classname`
+
+## Notes
+
+- Encourage automated linting (ESLint + prettier-plugin-tailwindcss) post-audit
+- Document class naming conventions (order: layout → size → spacing → typography → color → effect)
+- Track manual overrides (safelist patterns, arbitrary values) for future cleanup
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/bootstrap-shadcn-library.md

@@ -0,0 +1,96 @@
+# Bootstrap Shadcn/Radix Component Library
+
+> Task ID: atlas-bootstrap-shadcn  
+> Agent: Merovingian (Design System Builder)  
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `modernization`
+
+## Description
+
+Install and curate a Shadcn UI component library leveraging Tailwind v4, Radix primitives, and project design tokens. Establish shared utilities (`cn`, `cva`), Spinner/loading patterns, and documentation scaffold.
+
+## Prerequisites
+
+- Tailwind v4 configured with tokens (`@theme` + dark mode)
+- React/Next.js project with TypeScript
+- Node.js ≥ 18
+- Storybook (optional but recommended)
+
+## Workflow
+
+1. **Initialize Shadcn CLI**
+   ```bash
+   npx shadcn@latest init
+   ```
+   - Configure paths (`components`, `lib/utils.ts`)
+   - Enable TypeScript + Tailwind + Radix defaults
+
+2. **Install Core Utilities**
+   ```bash
+   npx shadcn@latest add button input card textarea badge skeleton spinner
+   ```
+   - Ensure `cn` helper uses `clsx` + `tailwind-merge`
+   - Add `Spinner` component for loading states (if not provided by template)
+
+3. **Map to Tokens**
+   - Replace hardcoded colors with semantic token classes (`bg-primary`, etc.)
+   - Align spacing/typography with design system scale
+   - Add dark mode variants (`dark:bg-background`)
+
+4. **Radix Integration**
+   - Install Radix primitives as required (`@radix-ui/react-slot`, etc.)
+   - Verify accessibility attributes and focus management remain intact
+
+5. **Variant & Utility Enhancements**
+   - Extend `cva` definitions to match project variants (density, destructive, ghost)
+   - Add shared loading pattern (Spinner + `isLoading` prop)
+   - Introduce compound variants for icon buttons, destructive actions
+
+6. **Documentation & Storybook**
+   - Create MDX or markdown docs for each component (`docs/components`)
+   - Optional: Add Storybook stories using auto-generated stories from `tasks/build-component`
+
+7. **Update State**
+   - Append to `.state.yaml` (`tooling.shadcn`) with components installed, timestamp
+   - Record any local overrides or follow-up actions
+
+## Deliverables
+
+- Populated `components/ui/` directory with Shadcn components
+- Updated `lib/utils.ts` (`cn`, `formatNumber`, etc. if needed)
+- Component documentation & Storybook stories (optional)
+- `.state.yaml` entries for `tooling.shadcn`
+
+## Success Criteria
+
+- [ ] Shadcn CLI initialized with Tailwind v4-compatible paths
+- [ ] Core components (button/input/card/etc.) installed and tokenized
+- [ ] `cn` helper + `class-variance-authority` configured
+- [ ] Spinner/loading pattern standardized across components
+- [ ] Documentation/Storybook updated with usage examples
+- [ ] `.state.yaml` reports bootstrap timestamp and component list
+
+## Failure Handling
+
+- **Shadcn CLI fails to initialize:** Verify Node.js >=18, clear npm cache, delete node_modules and package-lock.json, reinstall dependencies, retry init with --force flag if persistent
+- **Component token mapping breaks existing styles:** Create parallel tokenized versions with -v2 suffix, run visual regression tests, gradually migrate consumers, maintain backward compatibility aliases until full migration
+- **Radix primitive version conflicts with existing dependencies:** Audit dependency tree for conflicting peer dependencies, use npm overrides or resolutions to force compatible versions, document override rationale in package.json comments
+- **Storybook cannot import Shadcn components:** Check Storybook webpack/Vite config for TypeScript path alias resolution, add paths from tsconfig to Storybook config, verify @/ alias points to correct src directory
+
+## Notes
+
+- Prefer named exports (`export { Button }`) for tree-shaking
+- Maintain parity between Shadcn variants and design token aliases
+- Document manual updates (Shadcn is copy/paste — no automatic updates)
+- Schedule regular audits to pull upstream improvements intentionally
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.