🎨 TidyFactor Styler v1.3.0

The Production Framework Styler, Surgical RTL Redesign & Anti-Slop UI Engine for AI Coding Agents

Give Google Antigravity, Claude Code, Cursor, OpenAI Codex, or Windsurf a production-grade UI transformation engine that operates directly inside your live codebase — without inventing duplicate style layers, alien dependencies, or per-page CSS drift.

English • العربية • فارسی • Español • Português • 简体中文 • Deutsch • Français

📚 Table of Contents

• 🎯 Why TidyFactor/Styler
• 🚀 Quick Start
• 🌟 Value Proposition: When to Use Styler?
• ⚡ 13-Stage Command Dispatcher Architecture
• 🛠️ The 8 Production Workflows
• 🌐 Supported Production Stacks
• 🇸🇦 Native Arabic & Surgical RTL Engineering
• 🛡️ Anti-Slop Governance & Quality Bar
  • 1. The 6-Axis Pre-Emit Self-Critique (P, H, E, S, R, V)
  • 2. The 8-State Component Interaction Matrix
• ❓ FAQ
• 🏛️ The TidyFactor Ecosystem
• 🏛️ TidyFactor Skill Methodology & Governance
• 🤝 Contributing
• 👨‍💻 Support
• 📜 License

🎯 Why TidyFactor/Styler

[!IMPORTANT] The Styler Manifesto: Why Raw AI Codegen Produces Bland UI
Raw LLMs default to the statistical mean: generic purple gradients, missing interactive micro-states, arbitrary inline styles, and broken directional CSS margins (mr-*, ml-*).
TidyFactor Styler is the surgical in-codebase antidote: It enforces a zero-drift, framework-native contract that refactors live components, injects production-grade RTL ergonomics, and respects your existing design tokens without breaking upstream architecture.

TidyFactor/Styler enforces a strict "Conform, Don't Compete" engineering contract: it detects your project's active framework, inspects existing design tokens, and outputs stack-native components that look like your senior frontend architect wrote them.

⚡ The Before & After Difference: Raw AI Prompting vs. Styler In-Codebase Polish

```html
<!-- ❌ RAW AI GENERATION (Generic, Fragile, LTR-Hardcoded) -->
<button class="bg-purple-600 hover:bg-purple-700 text-white font-bold py-2 px-4 rounded mr-3 shadow-lg flex items-center gap-2">
  <span>Submit Order</span>
  <svg class="w-4 h-4 ml-1" fill="none" viewBox="0 0 24 24"><!-- hardcoded LTR arrow --></svg>
</button>
<!-- Flaws: Hardcoded mr/ml breaks RTL; Generic purple gradient; Missing focus-visible, active, disabled, and loading states; Ignores project design tokens -->
```
<!-- slide -->
```html
<!-- ✅ TIDYFACTOR STYLER POLISH (Production-Grade, Token-Aligned, Native RTL) -->
<button class="btn-primary inline-flex items-center justify-center gap-2 font-medium transition-all duration-150 ease-out focus-visible:ring-2 focus-visible:ring-primary/40 focus-visible:outline-none disabled:opacity-50 disabled:pointer-events-none data-[state=loading]:cursor-wait data-[state=loading]:opacity-80 active:scale-[0.98] me-3">
  <span>تأكيد الطلب / Submit Order</span>
  <svg class="w-4 h-4 rtl:rotate-180 transition-transform" aria-hidden="true" viewBox="0 0 24 24"><!-- bidi-aware --></svg>
</button>
<!-- Strengths: Native logical properties (me-3); Bidi-safe icon rotation; Full 8-state interaction matrix; Strictly scoped to existing design tokens -->
```

🚀 Quick Start

1. Skill Injection via CLI

# Add Styler directly into your current project workspace
npx @tidyfactor/cli-styler add-skill

2. Workspace Installation per AI Agent

Once installed, simply invoke /brief, /component, /section, or /redesign inside your AI agent chat to begin surgical UI engineering!

🌟 Value Proposition: When to Use Styler?

graph TD
    Intent{"What are you building?"}
    Intent -->|"Standalone prototype from zero"| D["🎨 tidyfactor-design<br/>(Zero-build HTML prototype)"]
    Intent -->|"New framework skeleton"| S["🏗️ Architecture Track<br/>(tidyfactor-next, tidyfactor-php, etc.)"]
    Intent -->|"Real existing codebase UI work"| ST["💎 tidyfactor-styler<br/>(Production Component/Section/Page UI)"]

⚡ 13-Stage Command Dispatcher Architecture

tidyfactor-styler exposes 13 precision slash commands organized into a modular dispatch architecture:

graph LR
    SK["💎 SKILL.md<br/>(Dispatcher Router)"]
    SK --> C0["Discovery<br/>(brief)"]
    SK --> C1["Component Operations<br/>(component)"]
    SK --> C2["Surface Operations<br/>(section, page, redesign)"]
    SK --> C3["Architecture & Shell<br/>(layout, nav-footer)"]
    SK --> C4["Design System & Brand<br/>(typography, palette, assets, styles)"]
    SK --> C5["Engineering Quality<br/>(rtl, motion)"]

🛠️ The 8 Production Workflows

Every task follows a strict, single-outcome workflow ending in an automated validation checklist:

1. brief.md: Pre-flight CDL Discovery $\rightarrow$ Framework Baseline Lock $\rightarrow$ Brand Token Mapping $\rightarrow$ .tidyfactor/styler-brief.md Cache.
2. component-create.md: Design Read $\rightarrow$ Variant & State Mapping $\rightarrow$ Stack-Native Implementation $\rightarrow$ Pre-Emit Critique $\rightarrow$ Verification.
3. component-redesign.md: Current State Audit $\rightarrow$ Intent & Direction Selection $\rightarrow$ Scoped Refactoring $\rightarrow$ Zero Regression Check.
4. section-create.md: Macrostructure Alignment $\rightarrow$ Layout Archetype Rhythm $\rightarrow$ Inner Component Composition $\rightarrow$ Responsive Polish.
5. section-redesign.md: Section Scope Isolation $\rightarrow$ Hierarchy Elevation $\rightarrow$ Visual Anchor Refresh $\rightarrow$ Mobile Grid Audit.
6. page-create.md: Page Archetype Blueprint $\rightarrow$ Nav/Footer Selection $\rightarrow$ Section Assembly $\rightarrow$ SEO & Metadata Injection.
7. page-redesign.md: Global Visual Cohesion $\rightarrow$ Conversion Path Optimization $\rightarrow$ Typography Harmony $\rightarrow$ Performance Budget.
8. rtl-audit-fix.md: Directional CSS Elimination $\rightarrow$ Logical Properties Refactor $\rightarrow$ Bi-directional Icon Inversion $\rightarrow$ Font Hierarchy Tuning.

🌐 Supported Production Stacks

tidyfactor-styler inspects your codebase and binds dynamically to your target stack's architecture:

🇸🇦 Native Arabic & Surgical RTL Engineering

1. Logical CSS Properties Enforcement

tidyfactor-styler eliminates legacy directional styles (margin-left, float: right, left: 0) in favor of modern logical CSS:

/* Standard Logical Property Architecture */
.styler-card {
  margin-inline-start: 1.5rem;    /* Replaces margin-left / margin-right */
  padding-inline-end: 1.25rem;    /* Replaces padding-right / padding-left */
  inset-inline-start: 0;          /* Replaces left / right */
  text-align: start;              /* Replaces text-align: left */
  border-start-start-radius: 8px; /* Logical corner radius */
}

2. Letterform-Aware Arabic Typography

Arabic script requires specific line-height and letter-spacing compensation:

• Never use negative letter-spacing (tracking) on Arabic text (it breaks cursive glyph connections).
• Increase line-height by +15–20% compared to Latin typography to accommodate ascenders and descenders.
• Mood-Routed Font Pairings:
  • Modern SaaS / Interface: Cairo / Tajawal + Inter / Outfit
  • Editorial / High-Trust B2B: IBM Plex Arabic + IBM Plex Sans
  • Luxury / Creative: El Messiri (never below 24px) + Plus Jakarta Sans

🛡️ Anti-Slop Governance & Quality Bar

1. The 7-Axis Pre-Emit Self-Critique (P, H, E, S, R, V, D)

Before emitting code, the agent evaluates output against the 7-Axis Anti-Slop Rubric (memory/quality-bar.md / /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */):

• P — Palette Harmony (0–10): Strict WCAG 2.1 AA contrast; no generic AI purple/pink gradients without explicit brand mandate.
• H — Hierarchy & Rhythm (0–10): Clear visual anchor; intentional whitespace sizing using a 4px/8px baseline grid.
• E — Execution Fidelity (0–10): Full semantic HTML5; no empty <div> soup or misplaced wrappers.
• S — State Completeness (0–10): All 8 component states implemented.
• R — RTL Correctness (0–10): 100% logical CSS properties; proper icon inversion for directional arrows.
• V — Variety & Distinction (0–10): Distinct design school character; zero default Bootstrap-like look.
• D — Decision Alignment (0–10): Strict compliance with .tidyfactor/styler-brief.md architectural parameters.

2. The 8-State Component Interaction Matrix

Every interactive component must provide complete visual coverage for:

1. default: Baseline rest state with clear affordance.
2. hover: Subdued lift or contrast elevation (transition $\le 150\text{ms}$).
3. active: Pressed micro-scale ($0.98$) or inset depth.
4. focus-visible: 2px offset focus ring for keyboard accessibility.
5. disabled: Reduced opacity ($0.5$), cursor: not-allowed, pointer-events disabled.
6. loading: Skeleton loader or accessible spinner preventing layout shifts.
7. empty: Welcoming empty state illustration and actionable call to action.
8. error: Semantic danger state with accessible error description.

❓ FAQ

🏛️ The TidyFactor Ecosystem

TidyFactor is a modular web architecture and AI coding agent skill ecosystem built on clear separation of concerns across the product lifecycle:

TidyFactor Organization (github.com/TidyFactor)
│
├── Design Skills
│   ├── Cinematic    → Experience / "Wow"     (Apple × Cartier Scroll-Driven Landing Pages)
│   ├── Design       → Prototype / "Build"    (Code-Native UI Design Engine & Figma Alternative)
│   └── Styler       → Production / "Ship"    (Framework Styler & RTL Polish Engine)
│
├── Development Skills
│   ├── HTML         → Content & Static       (Semantic SEO & Static Platform Starter)
│   ├── HTMX         → Hypermedia             (Server-Driven Micro-Interactions)
│   ├── JS           → Vanilla SPA            (Framework-Free Reactive ES Modules)
│   ├── PHP          → Server-Rendered        (Modern PHP 8.x Component UI & Architecture)
│   └── Next         → Multi-Tenant SaaS      (Next.js 16, React 19, Supabase RLS & Dev-Perf)
│
└── Growth Skills
    └── Marketing    → Growth / Revenue       (Direct Response, Pillar SEO & Content Lifecycles)

💎 Frontend Triad

                TidyFactor
                    │
          ┌─────────┼─────────┐
          │         │         │
      Cinematic   Design    Styler
          │         │         │
      Experience Prototype Production
          │         │         │
        "Wow"      "Build"   "Ship"

📦 Community Package & Skill Parity

🏛️ TidyFactor Skill Methodology & Governance

tidyfactor-styler passes all 13 Architectural Governance Rules under tidyfactor-skill-architect:

1. ✅ Dispatcher Discipline: SKILL.md routes commands without executing tasks (~350 tokens).
2. ✅ One Workflow = One Outcome: Every workflow has a single deliverable with an explicit validation checklist.
3. ✅ Operational Memory: Pure design patterns, token schemas, and typography rules—zero narrative prose.
4. ✅ No Empty Structures: Clean, flattened architecture without single-file folders.
5. ✅ Philosophy Isolation: Technical execution separated from marketing commentary.
6. ✅ Trigger-Justified Growth: Commands added per verifiable UI engineering lifecycle stages.
7. ✅ Security & Quality Bar: Automated pre-emit self-critique rubric and 8-state interaction matrices.
8. ✅ Cross-Platform Parity: 100% identical behavior across Antigravity, Claude Code, Cursor, and Codex.
9. ✅ Platform Compatibility: Frontmatter double-quotes and valid YAML parsing.
10. ✅ Tool Permission Declaration: Explicit scope for tools and mutations.
11. ✅ Memory Freshness: Operational memory timestamps (last-verified: YYYY-MM-DD).
12. ✅ Skill vs MCP Boundary: Knowledge in skills, live state in MCP/CLI.
13. ✅ Two-Tier Multi-Language Documentation: Canonical technical documentation + 8-language localized guides.

🤝 Contributing

We welcome community contributions, custom stack adapters, and workflow refinements!

Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a Pull Request. All proposed workflows and memory extensions must satisfy the tidyfactor-skill-architect governance rules.

👨‍💻 Support

• 🌐 Website: tidyfactor.com
• 📚 Documentation: tidyfactor.com/documentation
• 🤝 Commercial Partner: Alwkala Digital Agency
• 🐙 GitHub Organization: github.com/TidyFactor
• 📧 Inquiries: [email protected]

👨‍💻 Organization & Support

• 🌐 Official Website: https://tidyfactor.com/
• 📚 Official Documentation: https://tidyfactor.com/documentation
• 🤝 Official Partner Website: Alwkala Digital Agency
• 🐙 GitHub Organization: github.com/TidyFactor
• 📧 Business Inquiries: [email protected]
• 📱 WhatsApp: +20 101 665 6899
• 📞 Phone: +20 101 665 6899
• 📍 Location: Cairo, Egypt

📜 License

Licensed under the Apache License 2.0. Copyright (c) 2026 TidyFactor & Alwkala.