---

📚 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.

Dimension	Generic AI Prompting / Prototypers	tidyfactor-styler
Operating Environment	Isolated demo files or new sandboxes	Live, existing codebases (React/Next.js, PHP, WordPress, HTML)
Styling Conformance	Injects new alien CSS rules or duplicate Tailwind layers	Adopts your active Tailwind config, CSS variables, or class conventions
Scope Control	Sloppy edits that accidentally break global layouts	Strictly scoped refactoring (component touches only component)
Arabic & RTL Support	Literal flipping or broken directional margins (mr-*, left-*)	Native Logical CSS (ms-*, pe-*, start-*) + letterform font scaling
Anti-Slop Quality	Generic purple AI gradients and missing interactive states	7-Axis pre-emit self-critique (P, H, E, S, R, V, D) + mandatory 8-state interaction matrix
Context Consumption	Giant unorganized design dumps (10k+ tokens)	Context-efficient dispatcher (~350 tokens at start, loads on demand)

⚡ 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 -->
```

---

🚀 Installation & Quick Start

Choose your preferred installation method:

Option A: Via TidyFactor CLI (Recommended)

Install directly using the official ecosystem package runner into your active workspace:

npx @tidyfactor/cli add styler

Or if you have the CLI installed globally (npm i -g @tidyfactor/cli):

tidyfactor add styler

Option B: Via Open Agent Skills Ecosystem (skills.sh / Vercel Labs)

Install using the universal multi-agent standard across all supported IDEs (Cursor, Antigravity, Claude Code, Windsurf, Trae, Codex):

npx skills add tidyfactor/styler

Option C: Standalone Zero-Dependency Runner (NPM Direct)

Run the dedicated skill installer directly with automatic cache invalidation:

npx @tidyfactor/styler@latest

2. Workspace Installation per AI Agent

AI Agent	Workspace Skill Path
Google Antigravity	.agents/skills/tidyfactor-styler/ or global ~/.gemini/config/skills/
Claude Code	.claude-skill/skills/tidyfactor-styler/
Cursor / Codex / Windsurf	.agents/skills/tidyfactor-styler/

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)"]

For Frontend Developers	For Fullstack & Agency Teams	For AI Coding Agents
Conform, Don't Compete: Adopts your existing naming, Tailwind config, and styling conventions without creating a parallel CSS system.	Full Stack Agnostic: Seamlessly switches between Next.js, PHP, WordPress, and Vanilla stacks with zero manual prompt calibration.	Token-Efficient Dispatcher: Lightweight SKILL.md entry router loads only ~350 tokens at launch, pulling memory only when required.
Component-Scoped Precision: Component redesigns touch only the component definition and its immediate usages — never neighboring widgets.	Arabic / RTL First-Class: Automated logical CSS properties (ms-*, pe-*, start-*), letterform-aware font scaling, and bidi isolation.	Anti-Slop Certified: 6-axis pre-emit self-critique (P, H, E, S, R, V) blocks generic AI purple gradients and sloppy styling tells.
8-State Interaction Matrix: Guarantees default, hover, active, focus, disabled, loading, empty, and error states for all components.	Brand SSOT Integration: Automatically reads brand.json and maps design tokens to native CSS custom properties or framework theme vars.	Deterministic Checklists: Every workflow terminates with an explicit, quantifiable validation checklist before shipping.

---

⚡ 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)"]

Command	User Intent	What It Loads	Output & Value
brief	"Establish design brief / project baseline"	workflows/brief.md + memory/decision-points.md	Pre-flight interview caching target framework and design school.
component	"Create / Redesign this component"	workflows/component-create.md or component-redesign.md + component-anatomy.md + stacks/*.md	Production React/PHP/HTML component with 8-state coverage & CVA variants.
section	"Create / Restyle this section"	workflows/section-create.md or section-redesign.md + layout-archetypes.md + nav-footer-catalog.md	Scoped section surface with responsive rhythm and clean visual hierarchy.
page	"Build a new production page"	workflows/page-create.md + layout-archetypes.md + nav-footer-catalog.md + stacks/*.md	Complete page assembly strictly adhering to framework file conventions.
redesign	"Redesign this existing page"	workflows/page-redesign.md + layout-archetypes.md + nav-footer-catalog.md + quality-bar.md	High-impact visual overhaul with zero functional regression or broken state.
layout	"Select layout archetype / macrostructure"	memory/layout-archetypes.md + stacks/*.md	Matches product context to 1 of 8 macrostructure archetypes (editorial, interface, etc.).
nav-footer	"Select navigation & footer archetypes"	memory/nav-footer-catalog.md + typography-arabic.md + rtl-css-engineering.md	Chooses from N1–N9 navigation and Ft1–Ft8 footer archetypes with RTL alignment.
typography	"Pick/pair typography, incl. Arabic"	memory/typography-arabic.md	Applies 7 mood-routed font pairings (Cairo, Tajawal, El Messiri, Inter, Outfit).
palette	"Extract color palette & WCAG AA contrast"	memory/brand-tokens.md + memory/asset-tooling.md	Generates semantic token scales with automated WCAG 2.1 AA contrast scores.
assets	"Asset hygiene & image optimization"	memory/asset-tooling.md + memory/quality-bar.md	Compresses images, inspects dimensions, and processes image assets.
rtl	"Audit & fix RTL / Arabic correctness"	workflows/rtl-audit-fix.md + memory/rtl-css-engineering.md	Converts directional CSS to logical properties and fixes icon flipping rules.
motion	"Add / review motion and interaction"	memory/motion-principles.md	Orchestrates Framer Motion / Alpine transitions with prefers-reduced-motion a11y.
styles	"Choose a design direction / style movement"	memory/design-styles.md	Directs UI to a specific aesthetic movement (Modern SaaS, Editorial, Swiss, etc.).

---

🛠️ 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:

Target Framework	Styling Foundation	Component Architecture	Motion Engine
React / Next.js (App Router & Pages)	Tailwind CSS v4 / v3 or CSS Modules	Radix UI / shadcn/ui + CVA + clsx + tailwind-merge	Framer Motion (framer-motion)
PHP (TidyFactor / Flight / Medoo)	Tailwind CSS or Native CSS Custom Properties	Semantic HTML5 Partials (Plates / Blade / PHP Views)	Alpine.js (x-transition) or CSS Transitions
WordPress / Classic CMS	Modern Theme CSS / Gutenberg Styles	PHP Template Parts / Block Markup	Native CSS Keyframes / Vanilla JS
Static HTML / CSS / JS	Semantic CSS / Modern CSS Variables	Modular Component Blocks	Vanilla JS / CSS Transitions

---

🇸🇦 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

How is Styler different from tidyfactor-design?

tidyfactor-design creates standalone, zero-build clickable HTML prototypes in a separate demo directory. tidyfactor-styler operates directly inside your real codebase (Next.js, PHP, WordPress, HTML) modifying existing components and respecting your active CSS architecture.

Will Styler overwrite or mess up my existing Tailwind configuration?

Never. Styler follows the "Conform, Don't Compete" rule: it inspects your tailwind.config.js or CSS files and uses your existing utility classes and token definitions.

Which AI coding agents are supported?

Google Antigravity, Claude Code, Cursor, OpenAI Codex, and Windsurf are all supported with 100% behavioral parity.

How does Styler handle Arabic / RTL layouts?

Styler uses CSS Logical Properties (e.g. margin-inline-start, inset-inline-start, text-align: start) and handles icon flipping, line-height expansion, and Arabic font pairing automatically.

---

🏛️ 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

Track	Category	GitHub Repository	Agent Skill	NPM Package
Styler	Design	TidyFactor/Styler	tidyfactor-styler	@tidyfactor/styler
Design	Design	TidyFactor/Design	tidyfactor-design	@tidyfactor/design
Cinematic	Design	TidyFactor/Cinematic	tidyfactor-cinematic	@tidyfactor/cinematic
Next	Development	TidyFactor/Next	tidyfactor-next	@tidyfactor/next
HTML	Development	TidyFactor/HTML	tidyfactor-html	@tidyfactor/html
HTMX	Development	TidyFactor/HTMX	tidyfactor-htmx	@tidyfactor/htmx
JS	Development	TidyFactor/JS	tidyfactor-js	@tidyfactor/js
PHP	Development	TidyFactor/PHP	tidyfactor-php	@tidyfactor/php
Marketing	Growth	TidyFactor/Marketing	tidyfactor-marketing	@tidyfactor/marketing

---

🏛️ 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: hello@tidyfactor.com

---

👨‍💻 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: hello@tidyfactor.com
• 📱 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.