7.4 KiB
AI-Friendly Component Library
The Problem
Current architecture is optimized for human developers (DRY, reusable, flexible) but this makes AI editing fail. AI can't trace through ThemeProvider indirection, 40+ prop interfaces, nested component layers, and custom Tailwind scales. It hallucinates because it can't see the actual output.
The Solution
Shift from human-optimized to AI-optimized code:
- Explicit over implicit - All styles visible in file, no ThemeProvider magic
- Flat over nested - Direct components, no wrapper layers to trace through
- Concrete over abstract - Actual Tailwind classes, not prop names that map to hidden styles
- Standard over custom - Default Tailwind values AI already knows
- Simple over flexible - One way to do things, not 11 variants
Components become templates that AI reads, understands, and edits directly.
1. Backend-Driven Sections
Generated website repository only contains what is used, plus general UI components. Section components are stored on the backend and injected when needed, not bundled in the boilerplate.
Alternative: If backend approach takes too long, keep all sections in the boilerplate but with the new simplified structure defined below.
2. Props & Structure
Remove all styling/className props. AI edits classes directly in the component file.
Option A - Minimal props: Keep text, links, assets, arrays, icons as props. Backend passes content, AI edits props in page file.
Option B - No props: All content hardcoded in section file. Backend injects entire file with content baked in. AI edits section file directly. Maximum explicitness.
Flat structure: Sections use direct components (TextAnimation, Button, MediaContent) not wrapper components like TextBox that nest other components inside.
3. Framer Motion for Element Animations
Replace GSAP (ScrollTrigger, gsap.context(), ctx.revert()) with Framer Motion motion divs for cards, buttons, tags, and other elements. Use whileInView for scroll-triggered animations.
4. Simplified Tailwind & Single CSS File
Remove all custom Tailwind values (spacing, widths, gaps). Use default Tailwind classes.
Keep:
- Content width approach (for page width and carousels)
- Fluid font sizes (AI picks bad font sizes otherwise)
One globals.css file with:
- Color variables in
:root --radiusvariable, applied globally via@layer base- Card styles
- Button styles
- Utility classes (masks, animations) - consolidated, fewer variants
- Base styling (body defaults, scrollbar, heading font-family)
AI picks from a reference list of available styles and writes them directly to globals.css.
5. Remove ThemeProvider
Delete the entire ThemeProvider system. No dynamic style injection.
Card/button styles: AI chooses on backend, adds one card style, one primary button style, one secondary button style to globals.css.
Text animations: Remove TextBox component. Use simple TextAnimation component in section files with text and animationType props.
Button: Single components/ui/Button.tsx with text, href, and className (e.g. primary-button defined in globals.css).
Content width: Fixed value in globals.css.
Text sizing: Fixed values in globals.css. Future: AI picks from 3 presets on backend and adds to globals.css.
Background components: Remove all (aurora, grid, floatingGradient, etc.).
Fonts: Keep current logic.
6. New Folder Structure
src/
├── app/ # Pages
├── components/
│ ├── ui/ # Atomic UI components
│ └── [sections] # Section components flat, not nested (injected from backend)
├── hooks/ # Common hooks
├── lib/ # Utilities
└── styles/
└── globals.css # Single CSS file
Remove: providers/themeProvider/, multiple CSS files, button/ variants folder, text/ folder, background/ folder.
7. Atomic UI Components
Add simple, single-purpose components to components/ui/:
Button, TextAnimation, MediaContent, Toggle, Dropdown, Accordion, Avatar, Badge, Breadcrumb, Calendar, Chart, Checkbox, Form, Input, Label, Tooltip
Expand as needed.
8. Simplify Complex Components
Navbar: Separate navbar components instead of one with variants. AI chooses which one. Reduce to 4 navbars for now.
CardStack → GridLayout: Replace complex CardStack (mode, gridVariant, carouselThreshold, ~40 props) with simple wrapper. Children as items. Single prop: items per row (3 or 4). Under = grid, over = carousel. Carousel mode keeps controls (prev/next, progress bar). No title/description/animation props - sections handle all that directly. Remove timelines, grid configs, auto-carousel variants for now, refactor later.
TextBox: Remove completely. Use TextAnimation and Button directly in sections.
9. Consistent File Patterns
Every section file follows the EXACT same structure. AI sees one section, knows how all work.
Template:
1. IMPORTS (same order: react, framer-motion, ui components, icons)
2. CONTENT (variables at top if Option B)
3. COMPONENT (predictable JSX order)
4. EXPORT (always at bottom)
JSX order: tag → title → description → buttons → media (always same sequence)
10. Short Files, No Sub-components
Line limits:
- Sections: under 100 lines
- UI components: under 50 lines
Key rule: Don't split into sub-components to achieve this. Sub-components add nesting/indirection. Instead, simplify the section itself.
If a section is too long, it's too complex. Simplify the design, don't extract parts.
11. Content at Top
If using Option B (no props), put all editable content as variables at the very top of the file.
AI immediately knows: "edit content? check the top."
12. Remove Complex Components
Remove overly complex components for now. Add back simplified versions later if needed.
13. CSS Class Organization
Consistent class order: layout → spacing → sizing → typography → colors → effects
Keep className short. Too many classes = section too complex. Use global CSS (.card, .btn-primary) for repeated patterns.
No dynamic classes in sections. Avoid cls(condition && "class"). Keep it explicit.
One line if short, split by category if long.
Implementation Roadmap
Phase 1: Foundation (Delete)
- Delete
providers/themeProvider/(13 files) - Delete
components/background/(27 files) - Delete
components/Textbox.tsx - Delete
components/text/(GSAP TextAnimation) - Consolidate all CSS → single
styles/globals.css
Phase 2: Core Simplification
- Button → single
ui/Button.tsx(50 lines max) - Navbar → 4 separate components, no animation hooks
- TextAnimation → new Framer Motion version
- CardStack → simple GridLayout wrapper
Phase 3: Section Refactoring
- Remove all className/containerClassName props
- Remove useTheme() calls
- Each section under 100 lines
- Content variables at top (if Option B)
- Flat structure, no nested wrappers
Phase 4: Organize
- Create
components/ui/with atomic components - Move hooks to
hooks/folder - Update all imports
Current → Target
| Metric | Current | Target |
|---|---|---|
| Total files | ~270 | ~100 |
| Lines of code | ~25,000 | ~10,000 |
| Props per section | 20-40 | 5-10 |
| CSS files | 37 | 1 |
| Button variants | 11 | 1 |
| Navbar variants | 5 | 4 |