cleanui

Files (4)

• LICENSE
• README.md
• SKILL.md
• mobile-patterns.md · references/

SKILL.md (first lines)

# CleanUI — AI UI Design Enforcement Skill

> **STOP. Before you write ANY UI code, read this file.**
>
> You are an AI code generator with deeply ingrained UI habits that produce recognizable "AI-looking" output. This skill exists to override those habits and produce professional, human-designed interfaces.
>
> **Your process for every UI task:**
> 1. Think about what you would NORMALLY generate
> 2. Check each element against the HARD NO list below
> 3. Replace every violation with the specified alternative
> 4. Only then write the code

---

## HARD NO LIST — AUTOMATIC FAIL PATTERNS

If your output contains ANY of these, stop and fix before returning code.

### Typography
- **BANNED:** `font-extrabold` (800), `font-black` (900), `fontWeight: "800"`, `fontWeight: "900"`
- **USE INSTEAD:** `font-bold` (700) max. `font-semibold` (600) for section headings.
- **SELF-CHECK:** Search your code for "extrabold" and "black". Replace all with "bold".

### Logo / Trust Bars
- **BANNED:** Company names as identical plain text in identical bordered pills/boxes
- **USE INSTEAD:** Make each logo visually distinct — pair icons with names, vary weight/italic/tracking per logo, or use SVG logos
- **SELF-CHECK:** Do all logos look identical? Fix it.

### Uppercase / Letter Spacing
- **BANNED:** `tracking-[0.18em]`, `tracking-[0.2em]`, `tracking-[0.24em]` or any custom wide letter-spacing
- **BANNED:** More than 2 uppercase tracked labels on the entire page
- **USE INSTEAD:** Sentence case. If uppercase needed, `tracking-wider` (0.05em) max.

### Eyebrow Badges
- **BANNED:** Decorative pill/badge above headlines that restates what the headline says (e.g., "AI writing system for content teams")
- **USE INSTEAD:** Remove entirely, or use factual info: "Now in beta", "Trusted by 2,400 teams", "Free plan available"

### Hero Headlines
- **BANNED:** Headlines wrapping to 4+ lines on desktop
- **USE INSTEAD:** 4-8 words, max 2 lines. Rewrite shorter.
- **BANNED:** Subtitle longer than 2 sentences
- **USE INSTEAD:** 1-2 short sentences max.

### Decorative Copy
- **BANNED:** Ornamental labels like "Live pulse", "Night shift", "Operational clarity without the clutter"
- **USE INSTEAD:** Real data (status, counts, dates) or remove entirely. Every label must serve a function.

### Shadows
- **BANNED:** `shadow-xl`, `shadow-2xl`, blur above 8px on cards
- **USE INSTEAD:** `shadow-sm` or `shadow-none` with subtle border.

### Border Radius
- **BANNED:** Random mixing of `rounded-md`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-[24px]`, `rounded-[32px]`
- **USE INSTEAD:** Pick 2-3 values. Cards: 8-12px. Buttons: 6-8px (or `rounded-full` for pills). Inputs: 6-8px. Be consistent.

### Icons
- **BANNED:** Unicode characters as icons (`↑`, `↓`, `◌`, `⌂`, `◫`)
- **USE INSTEAD:** lucide-react (web), @expo/vector-icons (React Native), SF Symbols (iOS), Material Icons (Android)

### File Structure
- **BANNED:** Entire app in a single file
- **USE INSTEAD:** Separate: screens/pages, components, constants/theme, data, navigation

---

## LAYOUT RULES

### Match Layout to Content Type

| Content Type | Layout | Don't Use |
|---|---|---|
| Images/visual (food, travel, products) | Horizontal carousels, image grids, hero images | Text-only vertical lists |
| Data/numbers (finance, fitness, analytics) | Stat cards, progress bars, metric grids | Hero image cards |
| Feed (social, news, posts) | Full-width stacking cards, infinite scroll | Sectioned layout with drag handles |
| Items to browse (e-commerce, tasks, email) | Vertical list with search/filters | Hero sections |
| Multimedia (streaming, music, podcasts) | Horizontal scroll shelves (Netflix-style) | Vertical lists |
| Chat/messages | Contact list + chat detail | Hero cards or stat grids |
| Maps/location | Map view + bottom sheet overlay | Standard list layout |

### Anti-Templating Rules
- **NEVER use the same layout skeleton for every app.** Read the prompt, identify the content type, pick the right layout.
- **NEVER use ALL of these together:** hero card + grid buttons + drag handle + segmented control + vertical list. That's a template.
- If the app is image-heavy, show **actual images** — thumbnails, photos — not just icons in rounded squares.
- Use **horizontal scrolls** (`FlatList horizontal`, CSS `overflow-x-auto`) for categories, featured items, content shelves. AI generators underuse these.

---

## DESIGN TASTE

### Color Restraint
- Monochrome or near-monochrome palettes often look better than colorful ones.
- Color should appear mainly in actions (buttons, links), status (badges), and highlights (selected states). Not on everything.
- Dark elements (cards, sections) are justified ONLY when they represent a real-world object (credit card, media player, code block) or create deliberate visual rhythm. Not just "for variety."

### List Items
- **NEVER use letter initials as the only identifier.** Use category-specific icons (utensils for restaurant, bus for transport, repeat for subscription) in rounded squares.
- Always include **metadata**: date/time, category, status. "Restaurant" feels fake. "Restaurant · May 5 · 14:28" feels real.

### Filters
- Any list with 5+ items should have a filter or segmented control.
- Segmented control: pill-track style with solid fill on selected segment.

### Action Buttons
- Borderless style often looks cleaner: icon in muted-background square + label below. No card wrapper, no shadow, no border needed.

---

## MOBILE RULES

See [Mobile Patterns Reference](references/mobile-patterns.md) for full iOS color palettes, Android Material 3 tokens, component guidelines, and code examples.

### All Platforms
- Use **real navigation libraries**, not custom View-based nav bars. React Native: `@react-navigation/bottom-tabs`. iOS: `TabView`. Android: Material `NavigationBar`.
- **NEVER build floating pill-shaped bottom nav bars.** No `position: absolute`, no `borderRadius: 28`, no dark floating pill.
- Use **Platform.select()** or **Platform.OS** for conditional styling in React Native.
- Define design tokens (colors, spacing, radii, typography) in a constants file.
- Handle 3 states per screen: loading (skeletons), content, empty.

### iOS

From nengoxx/ctrl-b, GPL-3.0.

More from nengoxx/ctrl-b