Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "suaveplan-frontend-design",
|
||||
"version": "1.0.0",
|
||||
"description": "Suaveplan-specific frontend design skill for React + Tailwind + shadcn/ui"
|
||||
}
|
||||
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||
---
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces for the Suaveplan monorepo. All output MUST use **React 19 + TypeScript + Tailwind CSS + shadcn/ui** and follow Suaveplan CLAUDE.md conventions.
|
||||
|
||||
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||
|
||||
## Required Stack
|
||||
|
||||
All frontend code MUST use:
|
||||
|
||||
- **React 19** with TypeScript generics and strict types
|
||||
- **Tailwind CSS** for styling (via utility classes, no inline styles)
|
||||
- **shadcn/ui** components from `@suaveplan/react-ui` as the base component library
|
||||
- **`cn()` utility** from `@suaveplan/react-ui` for conditional class merging (clsx + tailwind-merge)
|
||||
- **CSS variables** for theming (defined in Tailwind config or `:root`)
|
||||
- **Motion** (framer-motion) for React animations when available; CSS transitions/animations for simpler effects
|
||||
|
||||
### Available Suaveplan Libraries
|
||||
|
||||
Use these internal packages instead of external alternatives:
|
||||
|
||||
| Need | Use | Import |
|
||||
|------|-----|--------|
|
||||
| UI primitives (Button, Dialog, Card, etc.) | `@suaveplan/react-ui` | `import { Button } from '@suaveplan/react-ui'` |
|
||||
| Class merging | `cn()` from `@suaveplan/react-ui` | `import { cn } from '@suaveplan/react-ui'` |
|
||||
| Forms + validation | `@suaveplan/react-forms` | `import { Form } from '@suaveplan/react-forms'` |
|
||||
| Data tables | `@suaveplan/react-data-table` | `import { DataTable } from '@suaveplan/react-data-table'` |
|
||||
| Toast / notifications | `@suaveplan/react-notifications` | `import { toast } from '@suaveplan/react-notifications'` |
|
||||
| Auth components | `@suaveplan/react-auth` | `import { LoginForm } from '@suaveplan/react-auth'` |
|
||||
| Timeline / Gantt / Calendar | `@suaveplan/react-timeline` | `import { Timeline, Gantt, Calendar } from '@suaveplan/react-timeline'` |
|
||||
| Media players | `@suaveplan/react-media` | `import { MediaPlayer } from '@suaveplan/react-media'` |
|
||||
| i18n / translation | `@suaveplan/react-translate` | `import { useTranslation } from '@suaveplan/react-translate'` |
|
||||
| Consent overlays | `@suaveplan/react-consent-overlay` | `import { ConsentOverlay } from '@suaveplan/react-consent-overlay'` |
|
||||
| Drive sharing UI | `@suaveplan/drive-react-sharing` | `import { ShareDialog } from '@suaveplan/drive-react-sharing'` |
|
||||
| Email templates | `@suaveplan/email-templates` | `import { WelcomeEmail } from '@suaveplan/email-templates'` |
|
||||
|
||||
**NEVER** install or import external UI libraries (Material UI, Chakra, Ant Design, Mantine, Radix directly, etc.) when a Suaveplan equivalent exists. Import shadcn/ui primitives from `@suaveplan/react-ui`.
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||
|
||||
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||
- **Constraints**: Must use React + Tailwind + shadcn/ui. Must be tree-shakeable. Must follow Suaveplan file structure conventions.
|
||||
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||
|
||||
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||
|
||||
Then implement working code that is:
|
||||
|
||||
- Production-grade, functional, and type-safe
|
||||
- Visually striking and memorable
|
||||
- Cohesive with a clear aesthetic point-of-view
|
||||
- Meticulously refined in every detail
|
||||
- Tree-shakeable with proper exports
|
||||
|
||||
## Frontend Aesthetics Guidelines
|
||||
|
||||
Focus on:
|
||||
|
||||
- **Typography**: Use Tailwind's font system with custom font families defined in `tailwind.config`. Avoid generic system fonts. Pair a distinctive display font with a refined body font using `font-display` and `font-body` custom utilities. Load via `@fontsource` packages or Google Fonts with `next/font`.
|
||||
- **Color & Theme**: Use Tailwind CSS variables and shadcn/ui theming. Define colors in HSL format for shadcn compatibility. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Use `dark:` variants for dark mode support.
|
||||
- **Motion**: Use Motion (framer-motion) for component animations — `AnimatePresence`, `motion.div`, staggered children via `variants`. Use Tailwind's `transition-*`, `animate-*` utilities for simpler effects. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
|
||||
- **Spatial Composition**: Use Tailwind's grid/flex utilities creatively. Unexpected layouts with `grid-cols-[custom]`, asymmetric `gap-*`, overlapping with negative margins or `absolute` positioning. Generous `space-*` or controlled density.
|
||||
- **Backgrounds & Visual Details**: Create atmosphere with Tailwind gradients (`bg-gradient-to-*`), backdrop blur (`backdrop-blur-*`), shadows (`shadow-*`), and custom CSS for noise textures, geometric patterns, or grain overlays. Use `before:` and `after:` pseudo-elements via Tailwind for decorative effects.
|
||||
|
||||
### shadcn/ui Integration
|
||||
|
||||
- Build on top of shadcn/ui primitives — extend them, don't replace them
|
||||
- Use `cn()` from `@suaveplan/react-ui` for all conditional class composition
|
||||
- Override shadcn/ui defaults with Tailwind classes, not inline styles
|
||||
- Respect the `data-*` attributes shadcn uses for state styling
|
||||
- Example pattern:
|
||||
|
||||
```tsx
|
||||
import { Button } from '@suaveplan/react-ui';
|
||||
import { cn } from '@suaveplan/react-ui';
|
||||
|
||||
interface ActionButtonProps {
|
||||
variant?: 'primary' | 'danger';
|
||||
className?: string;
|
||||
children: React.ReactNode;
|
||||
}
|
||||
|
||||
export function ActionButton({ variant = 'primary', className, children }: ActionButtonProps) {
|
||||
return (
|
||||
<Button
|
||||
className={cn(
|
||||
'relative overflow-hidden transition-all duration-300',
|
||||
variant === 'primary' && 'bg-emerald-600 hover:bg-emerald-700 hover:shadow-emerald-500/25 hover:shadow-lg',
|
||||
variant === 'danger' && 'bg-rose-600 hover:bg-rose-700 hover:shadow-rose-500/25 hover:shadow-lg',
|
||||
className
|
||||
)}
|
||||
>
|
||||
{children}
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
NEVER use:
|
||||
|
||||
- Generic AI-generated aesthetics (overused font families like Inter/Roboto/Arial, cliched purple gradients on white, predictable layouts)
|
||||
- Inline styles — use Tailwind classes exclusively
|
||||
- External UI libraries when a `@suaveplan/*` equivalent exists
|
||||
- `vi.mock()` or `jest.mock()` in tests — use real implementations
|
||||
- Files over 250 lines (code) or 500 lines (tests)
|
||||
- `tsc` directly — use `bun run build` (Vite/tsup)
|
||||
- TODO comments or placeholder implementations
|
||||
|
||||
NEVER converge on common choices (Space Grotesk, etc.) across generations. Vary between light and dark themes, different fonts, different aesthetics.
|
||||
|
||||
## Suaveplan Code Standards
|
||||
|
||||
All generated frontend code MUST follow:
|
||||
|
||||
1. **Max 250 lines per file** — split components into smaller focused modules
|
||||
2. **TypeScript generics** — components should accept generic type parameters where applicable
|
||||
3. **Each component gets its own folder** with: `.tsx`, `.test.tsx`, `.stories.tsx`, `.types.ts` (if needed), `.md`
|
||||
4. **Storybook stories required** — default story, playground with controls, key variant stories
|
||||
5. **Playwright `.spec.ts`** for E2E testing of interactive components
|
||||
6. **Tree-shakeable** — use named exports, no side effects, declare `sideEffects: false`
|
||||
7. **No re-exports** — import directly from source packages
|
||||
8. **`workspace:*`** for internal dependencies
|
||||
9. **CSS classes use `sp-` prefix** for custom component-specific styles (matches existing convention)
|
||||
10. **Accessibility** — ARIA roles, keyboard navigation, focus management, screen reader support
|
||||
|
||||
### File Structure Pattern
|
||||
|
||||
```text
|
||||
components/
|
||||
my-component/
|
||||
my-component.tsx # Implementation (max 250 lines)
|
||||
my-component.test.tsx # Vitest unit tests (max 500 lines)
|
||||
my-component.stories.tsx # Storybook stories
|
||||
my-component.types.ts # Type definitions
|
||||
my-component.md # Documentation with simple + advanced examples
|
||||
```
|
||||
|
||||
### Documentation (.md) Requirements
|
||||
|
||||
Every `.md` file must include:
|
||||
|
||||
- Purpose description (200+ words)
|
||||
- **Simple Example**: basic usage, getting started
|
||||
- **Advanced Example**: generics, composition, edge cases
|
||||
- API reference for all public exports
|
||||
- Design decisions and implementation notes
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
When building a frontend component/page:
|
||||
|
||||
1. Design direction chosen and documented
|
||||
2. Component file structure created (`.tsx`, `.test.tsx`, `.stories.tsx`, `.types.ts`, `.md`)
|
||||
3. TypeScript types/interfaces defined with generics where applicable
|
||||
4. Component implemented using React + Tailwind + shadcn/ui
|
||||
5. `cn()` used for all conditional class composition
|
||||
6. Accessibility attributes applied (ARIA, keyboard, focus)
|
||||
7. Storybook stories written (default, playground, variants)
|
||||
8. Unit tests written with Vitest (95%+ coverage target)
|
||||
9. Playwright E2E spec written for interactive behaviors
|
||||
10. Documentation written with simple + advanced examples
|
||||
11. File sizes verified (code <= 250 lines, tests <= 500 lines)
|
||||
12. Lint clean: `bun run lint --filter=@suaveplan/<package>`
|
||||
13. Types clean: `bun run typecheck --filter=@suaveplan/<package>`
|
||||
14. Tests passing: `bun run test --filter=@suaveplan/<package>`
|
||||
|
||||
Remember: Claude is capable of extraordinary creative work. Commit fully to a distinctive vision while respecting the Suaveplan stack and conventions.
|
||||
Reference in New Issue
Block a user