219 lines
7.4 KiB
Markdown
219 lines
7.4 KiB
Markdown
# 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`
|
|
- `--radius` variable, 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 |
|
|
|
|
---
|