Codex/design style library

README.en.md

@@ -0,0 +1,219 @@
+# openlayout
+
+[한국어](./README.md) | **English**
+
+A web layout library for choosing, comparing, and previewing website structures and design styles separately — with real webpage-style previews.
+
+openlayout is a layout/style dictionary that helps you quickly pick page structure and visual language before you start designing. It provides 96 layouts, 88 design styles, 10 style categories, and a webpage-style sample renderer. Each entry comes with recommended use cases, pros and cons, responsive behavior, accessibility checkpoints, a color palette, and Tailwind implementation hints.
+
+| Item | Value |
+| --- | --- |
+| Repository | https://github.com/pandaofwild/openlayout |
+| Last reviewed | 2026-06-03 |
+
+## Who it's for
+
+- Designers who need to quickly compare website structures
+- Frontend developers looking for base skeletons for landing pages, dashboards, docs, and commerce screens
+- Teams that want to check responsive behavior and accessibility at the same time
+
+## Key features
+
+- **Layout explorer**: Filter layouts by search term, category, purpose, and complexity.
+- **Full-stage preview**: View layouts large, like a real webpage background, on detail and compare pages.
+- **Floating detail panel**: The base screen shows only a small summary box; clicking floats up a panel with structure description and pros/cons.
+- **Compare view**: Select up to 3 layouts to compare recommended use, mobile support, density, and difficulty side by side.
+- **Design Style Library**: Explore 88 design styles by category, tag, and search term, and check color palettes and webpage-style samples on detail pages.
+- **Style application**: A design style chosen in `/design-styles` is applied to the preview tone of `/web-layouts` and `/web-layouts/compare`, and persisted in localStorage.
+- **Prompt palette**: Mix prompts to generate a custom color palette and apply it directly to the current layout preview.
+- **Image generation admin**: In a local environment with `OPENAI_API_KEY`, generate per-style reference images and save them to `public/generated/design-styles`.
+- **SVG controls**: Comparison arrows and the info/close/detail icons are managed as inline SVG.
+- **Implementation hints**: Provides Tailwind code examples and implementation tips per previewType.
+- **Project skills**: `skills/layout-recommender/SKILL.md` and `skills/design-style-recommender/SKILL.md` guide purpose-based layout/style recommendations.
+
+## Why it helps vibe coding
+
+- State your page purpose up front and you can quickly narrow down layout candidates. e.g. "SaaS dashboard landing", "brand campaign", "docs-style knowledge base".
+- Each layout carries its recommended use, situations to avoid, responsive behavior, and accessibility checkpoints, so you can pull design constraints straight into your prompt.
+- The large previews and floating description panels on the compare page make it easy to iterate with short feedback like "let's go with this structure" or "this one is weak on mobile".
+- `previewType` works like shorthand for implementation direction. e.g. `hero`, `card-grid`, `dashboard`, `docs`, `comparison`.
+- `DesignStyle` works like shorthand for visual direction. e.g. `brutalism`, `cyberpunk`, `luxury`, `organic-design`, `saas-style`.
+- For a new screen, the most reliable flow is: pick a structure from the layout dictionary first, then pick color/typography/mood from a design style, and finally hand components and copy off to a coding agent.
+
+## Quick start
+
+Requirements:
+
+- Node.js 22 or later
+- npm
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the dev server:
+
+```bash
+npm run dev
+```
+
+Open in your browser:
+
+```text
+http://localhost:3000/web-layouts
+```
+
+The root path (`/`) redirects to `/web-layouts`.
+
+## Main routes
+
+| Route | Contents |
+| --- | --- |
+| `/web-layouts` | Layout search, filters, and card list |
+| `/web-layouts/[slug]` | Structure description, pros/cons, responsive behavior, accessibility notes, live preview, code example |
+| `/web-layouts/compare` | Compare up to 3 layouts with large structure previews |
+| `/design-styles` | Design style search, category/tag filters, color palettes, webpage-style samples |
+| `/design-styles/[slug]` | Design style detail, color palette, typography/layout traits, related styles |
+| `/design-styles/generate` | Local reference image generation admin powered by the OpenAI Image API |
+
+## Image generation environment variables
+
+`/design-styles/generate` and `/api/design-style-images` are local admin features.
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_IMAGE_MODEL=gpt-image-1.5
+```
+
+- `OPENAI_API_KEY` is required.
+- `OPENAI_IMAGE_MODEL` is optional and defaults to `gpt-image-1.5`.
+- Generated results are saved to `public/generated/design-styles/{slug}.webp`.
+- The image generation route is restricted to local development; on read-only deployment platforms like Vercel, switch to external storage such as Blob/S3.
+
+## Open-source usage
+
+This project is distributed under the MIT License. See `LICENSE` for full terms.
+
+- How to contribute: `CONTRIBUTING.md`
+- Security reports: `SECURITY.md`
+- Local environment variable example: `.env.example`
+- CI: `.github/workflows/ci.yml`
+
+## Quality checks
+
+Run these before deploying or uploading changes.
+
+```bash
+npm run lint
+npm run build
+```
+
+## Tech stack
+
+- Next.js App Router
+- React
+- TypeScript
+- Tailwind CSS
+
+The layout catalog is static-data driven. No separate database or external API is required.
+
+## Project structure
+
+```text
+src/app/web-layouts/page.tsx              # Explorer page
+src/app/web-layouts/[slug]/page.tsx       # Layout detail page
+src/app/web-layouts/compare/page.tsx      # Compare page shell
+src/app/design-styles/page.tsx            # Design style library page
+src/app/design-styles/[slug]/page.tsx     # Design style detail page
+src/app/design-styles/generate/page.tsx   # Local image generation admin
+src/app/api/design-style-images/route.ts  # OpenAI Image API route
+src/data/webLayouts.ts                    # Layout catalog and generated metadata
+src/data/designStyles.ts                  # 88 design styles and generated metadata
+src/components/web-layout/                # Explorer, cards, previews, compare UI
+src/components/design-style/              # Style cards, filters, samples, generator UI
+src/components/style-preset/              # Global selected style provider
+src/components/ui/                        # Small shared UI primitives
+skills/layout-recommender/SKILL.md        # Purpose-based layout recommendation skill
+skills/design-style-recommender/SKILL.md  # Brand-tone-based style recommendation skill
+```
+
+Key components:
+
+| File | Role |
+| --- | --- |
+| `WebLayoutExplorer.tsx` | Search and filter state for the layout list |
+| `WebLayoutFilters.tsx` | Filter UI for search term, category, purpose, complexity |
+| `WebLayoutCard.tsx` | Layout card and thumbnail |
+| `LayoutStagePreview.tsx` | Full-background preview, floating summary, click-to-open description panel |
+| `LayoutPreview.tsx` | Browser-style preview utility with viewport switching |
+| `LayoutPreviewRenderer.tsx` | Large live preview templates per previewType |
+| `WireframeThumbnail.tsx` | Structure thumbnails used on cards and the compare screen |
+| `LayoutCodeExample.tsx` | Copyable Tailwind implementation example |
+| `WebLayoutCompare.tsx` | Compare page selection, SVG arrow navigation, large preview display |
+| `DesignStyleLibrary.tsx` | Search, filter, and applied state for the design style list |
+| `DesignStyleCard.tsx` | Design style card, color palette, webpage-style sample, apply button |
+| `DesignStyleSampleRenderer.tsx` | 10 webpage-style style samples per sampleType |
+| `StylePresetProvider.tsx` | Persists the selected design style and custom palette in localStorage |
+| `DesignStyleImageGenerator.tsx` | Style reference image generation admin UI |
+
+## Project skills
+
+`skills/layout-recommender/SKILL.md` is an internal skill a coding agent reads to recommend a layout that fits the intended use.
+
+`skills/design-style-recommender/SKILL.md` is an internal skill read to recommend a design style matching brand tone, industry, emotion, typography, and color direction.
+
+Example recommendation request:
+
+```text
+This is a B2B SaaS onboarding page. Trust and feature explanation matter, and it has to work on mobile too. Which layout is best?
+```
+
+The skill is designed to first check the category, `bestFor`, `notGoodFor`, `tags`, and `previewType` in `src/data/webLayouts.ts`, then briefly suggest a top candidate, alternatives, and structures to avoid.
+
+Example design style recommendation request:
+
+```text
+It's a premium beauty brand landing page, but it shouldn't be too flashy — it needs to look high-end. Which design style is best?
+```
+
+The design style skill suggests a top style, alternatives, and styles to avoid based on `category`, `tags`, `goodFor`, `useCases`, `palette`, and `sampleType` in `src/data/designStyles.ts`.
+
+## Adding a layout
+
+Layout data is managed in `src/data/webLayouts.ts`.
+
+1. Add a new entry to `layoutSeeds`.
+2. Provide `nameKo`, `nameEn`, `category`, `summary`, `previewType`, and `complexity`.
+3. Add `bestFor`, `notGoodFor`, and `tags` only when you need to override the defaults.
+4. Let the data builder generate `slug`, the long description, pros/cons, responsive notes, accessibility notes, implementation tips, and related layouts.
+
+When adding a new category, also add a description and defaults to `categoryGuides`.
+
+## Adding a design style
+
+Design style data is managed in `src/data/designStyles.ts`.
+
+1. Add a new entry to `styleSeedTuples`.
+2. Provide `slug`, `nameKo`, `nameEn`, `category`, `tone`, `tags`, and `sampleType`.
+3. If needed, add a 9-color palette for that slug to `palettes`.
+4. If a new category is needed, add visual traits, color notes, typography, and layout tendencies to `categoryProfiles`.
+5. Extend `DesignStyleSampleType` and `DesignStyleSampleRenderer.tsx` only when the existing 10 sample renderers can't express it.
+
+## Adding a preview type
+
+Add a new previewType when existing templates don't reveal the structure well enough.
+
+1. Extend the `PreviewType` union in `src/data/webLayouts.ts`.
+2. Add a structure description, responsive behavior, and implementation tips to `previewGuides`.
+3. Add a live preview renderer to `src/components/web-layout/LayoutPreviewRenderer.tsx`.
+4. Add a thumbnail diagram to `src/components/web-layout/WireframeThumbnail.tsx`.
+5. If the implementation differs from existing examples, add a Tailwind example to `src/components/web-layout/LayoutCodeExample.tsx`.
+
+## Writing and design notes
+
+- Write layout names and summaries practically. A reader should understand when to use a structure without opening the detail page.
+- Prefer concrete structure labels like `Header`, `Main`, `Sidebar`, `CTA`, `TOC`, `Product`.
+- Detail pages explain limits and trade-offs, not just benefits.
+- Long descriptions on the compare page are collapsed by default so the structure diagram can be scanned first.

README.md

@@ -1,5 +1,7 @@
 # openlayout
 
+**한국어** | [English](./README.en.md)
+
 웹사이트 레이아웃과 디자인 형식을 분리해서 고르고, 비교하고, 실제 웹페이지형 프리뷰로 확인하는 Web Layout Library입니다.
 
 openlayout은 디자인을 시작하기 전에 페이지 구조와 시각 언어를 빠르게 고를 수 있도록 만든 레이아웃/스타일 사전입니다. 96개의 레이아웃, 88개의 디자인 형식, 10개의 스타일 카테고리, 웹페이지형 샘플 렌더러를 제공하며, 각 항목은 추천 용도, 장단점, 반응형 동작, 접근성 체크포인트, 색상표, Tailwind 구현 힌트를 함께 보여줍니다.

docs/plans/2026-06-03-design-dictionary-design.md

@@ -0,0 +1,171 @@
+# Design Dictionary — Design Document
+
+> **Status:** Approved design (2026-06-03). Next step: create an implementation plan with the `writing-plans` skill.
+> **Supersedes direction of:** `docs/superpowers/plans/2026-06-02-design-style-library.md` (the design-style library is now one axis of a larger dictionary).
+
+---
+
+## 1. Vision & Concept Model
+
+**One-line product definition:** Before starting a design, freely combine *Style × Layout* to preview real webpage-like results, later explore down to the component level, and copy code or prompts from any result — a **design dictionary**.
+
+### The user's full desired direction (recorded verbatim in intent)
+
+The owner wants to:
+
+1. Build webs in many styles — pages that genuinely look *different* per style, not the same mock recolored.
+2. Build layouts in many styles — explore the structural skeleton together with style.
+3. Combine them — cross styles and layouts to view the resulting web instantly.
+4. Eventually explore by component too — a design dictionary source viewable per component.
+5. Copy from any result — source code or the generation prompt.
+
+Gallery-first now; code/prompt copy later.
+
+### Four browsing axes (concept model)
+
+| Axis | Definition | Example |
+| --- | --- | --- |
+| **Style** | Visual language — a bundle of color/typography/shape/spacing/decoration tokens | cyberpunk, minimal, brutalism |
+| **Layout** | Structural skeleton — the content-placement frame | hero, dashboard, card grid |
+| **Web** | Style × Layout = one finished page | "cyberpunk × dashboard" |
+| **Component** | Individual styled piece — *later* | button, card, nav |
+
+### The core shift
+
+From today's **"swap the palette only"** → a **full design-token system**: style controls color, typography, shape, spacing/density, decoration, and layout variation.
+
+---
+
+## 2. Token System Architecture
+
+### Problem
+
+Today only `DesignStyle.palette` (9 colors) actually drives the screen. `typography`, `layoutTraits`, etc. are *descriptive text* and are never applied to rendering.
+
+### Solution
+
+Introduce **`StyleTokens`** — the values a style actually uses to control the screen. Every token is emitted as a CSS variable; layout and component renderers read only those variables.
+
+```ts
+type StyleTokens = {
+  color:      { base, surface, text, muted, primary,
+                accent, accent2, accent3, border }      // inherits current palette
+  typography: { displayFont, bodyFont, weightDisplay,
+                weightBody, tracking, headingScale }     // font / weight / tracking
+  shape:      { radius, borderWidth, borderStyle }       // roundness / borders
+  space:      { density: 'airy' | 'normal' | 'tight',
+                gap, padScale }                          // whitespace / density
+  decoration: { shadow, glow, grain, gradient,
+                effect: 'none' | 'glitch' | 'scanline' | … } // decorative effects
+  layout:     { heroVariant, navStyle, alignment }       // layout variation hints
+}
+```
+
+### Application flow
+
+```
+DesignStyle.tokens
+  → StyleProvider emits CSS variables (--st-radius, --st-font-display, --st-shadow …)
+  → LayoutRenderer / ComponentRenderer use only var(--st-*)
+  → Switching style = swapping a variable bundle = whole screen updates live
+```
+
+### Scalability (the heart of approach C)
+
+Adding one style = filling in a `tokens` object only. Renderers are untouched → scaling to 88 styles becomes "data entry."
+
+### Defaults + overrides
+
+Per-category default tokens (e.g. the "minimal" family is `airy` + thin fonts); each style overrides only what it needs → minimizes the labor of filling 88 styles.
+
+### Migration
+
+Existing `palette` → absorbed into `tokens.color`. Descriptive fields (`typography: string[]`, etc.) stay as human-readable dictionary text; application is handled by the new `tokens`.
+
+---
+
+## 3. Pages / UX Structure
+
+### Route map (reuse existing assets; the combine view is the key new piece)
+
+| Route | Role | Status |
+| --- | --- | --- |
+| `/styles` | Style gallery (88, filter/search) | inherit & rename from `/design-styles` |
+| `/styles/[slug]` | Style detail — tokens, color, type + sample | inherit & strengthen |
+| `/layouts` | Layout gallery (96) | inherit from `/web-layouts` |
+| `/layouts/[slug]` | Layout detail — structure, responsive, a11y | inherit |
+| **`/studio`** | **Combine view: Style × Layout → finished web preview** | **new (core)** |
+| `/components` | Component dictionary | *later (Phase 6)* |
+
+Old URLs keep working via redirects (`/web-layouts` → `/layouts`, `/design-styles` → `/styles`).
+
+### `/studio` — combine view (the heart of the project)
+
+```
+┌─────────────┬──────────────────────────────┐
+│ left: control│   right: live web preview     │
+│             │                              │
+│ Style  [▼]  │   selected Style × Layout     │
+│ Layout [▼]  │   rendered with full tokens   │
+│ viewport[▣▢]│   like a real webpage         │
+│             │                              │
+│ [copy code] │   (changing style = instant)  │
+│ [prompt]    │                              │
+└─────────────┴──────────────────────────────┘
+```
+
+- Pick style/layout from dropdowns (or small thumbnail grids) to cross instantly.
+- Desktop/mobile viewport toggle.
+- The chosen combo is shareable/bookmarkable via URL query (`?style=cyberpunk&layout=hero`).
+- **Copy buttons** activate in Phase 5 (placeholder reserved first).
+
+### Gallery cards
+
+Each style/layout card shows a mini thumbnail with full tokens applied, so scanning the list alone makes the "genuinely different" quality visible.
+
+### Copy feature (Phase 5)
+
+From `/studio` and detail pages — ① code for the current combo (HTML or React+Tailwind) ② an AI generation prompt.
+
+---
+
+## 4. Phased Roadmap
+
+Each phase gates on `npm run lint` + `npm run build` passing.
+
+**Phase 1 — Token system foundation** (core of approach C, top priority)
+- New `StyleTokens` type + `StyleProvider` emits all tokens as CSS variables.
+- Per-category default tokens + per-style overrides.
+- Migrate existing `palette` → `tokens.color`.
+- Complete **8–12 representative styles** with full tokens for validation.
+
+**Phase 2 — Tokenize the layout renderer**
+- `LayoutPreviewRenderer` consumes not just color but typography/shape/spacing/decoration tokens.
+- Convert layout gallery (`/layouts`) + detail to token-based.
+- Validate: the same layout looks *genuinely different* across styles.
+
+**Phase 3 — Studio combine view**
+- New `/studio`: cross style × layout, URL-query sharing, viewport toggle.
+- Refresh gallery card thumbnails to full-token rendering.
+- Old-URL redirect compatibility.
+
+**Phase 4 — Fill all 88 styles**
+- With the token system validated, expand the rest as "token value entry."
+- QA visual difference per style.
+
+**Phase 5 — Copy feature**
+- Copy code (HTML / React+Tailwind).
+- Copy AI generation prompt.
+
+**Phase 6 — Component dictionary** (long term)
+- `/components`: explore style application per component (button, card, nav, …).
+
+---
+
+## Decisions Log
+
+- Deliverable: gallery-first now; code/prompt copy later.
+- Concept model confirmed: Style / Layout / Web (= Style × Layout) / Component.
+- Style must control everything: color, typography, shape, spacing/density, decoration, and layout variation.
+- Approach **C (token system first)** chosen over (A) broad-but-shallow and (B) deep-but-few.
+- The full long-term vision must be captured in this document (done above).