aiox-core 5.0.3 → 5.0.5

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

@@ -1,350 +0,0 @@
-# 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

@@ -1,101 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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.