ima2-front

# ima2 Frontend — Domain-Correct Frontend Engineering ## Setup ```bash npm install -g ima2-gen # install globally (Node.js >= 20) ima2 setup # first-time auth (GPT OAuth recommended) ima2 serve # start local server ima2 ping # verify ima2 capabilities --json # check models, limits, providers ima2 defaults --json # inspect default model/reasoning ``` **Agent bootstrap:** `ima2 ping` first. If unreachable: `ima2 serve &`. If not installed: `npm install -g ima2-gen && ima2 setup`. Use `ima2 skill path` to locate the skills directory; read `../ima2-uiux/SKILL.md` for design direction and `../ima2-front/SKILL.md` (this file) for implementation. Build production-grade frontend implementations from an established product/design direction. This skill owns HTML/CSS/component/runtime implementation, responsive behavior, accessibility wiring, visual verification, and frontend platform rules. > **Role separation:** For design judgment — typography/color/layout direction, UX decision > gates, product personalities, or vague visual briefs — load `ima2-uiux` first. This > skill implements the chosen direction; `ima2-uiux` makes the design decisions. > Implementation anti-slop enforcement stays here; design taste/pattern judgment lives there. > **C0/C1 work (small local patches):** For small patches, skip the full reference chain. ## Modular References > **Loading references via CLI:** > **Recommended: install skills to your agent's skill directory.** > ```bash > ima2 skill install --dir <agent-skill-path> # agent provides its own path > ima2 skill install --tmp # ephemeral fallback > ``` > The agent determines its own skill directory (e.g. `~/.codex/skills/`, > `./skills/`, etc.) and passes it via `--dir`. After install, SKILL.md and > `references/` are on disk — the agent reads them natively via relative paths. > > **Ad-hoc reading (without install):** > ```bash > ima2 skill front refs # list all reference modules with line counts > ima2 skill front ref motion # print one module (basename match) > ima2 skill front ref stacks/react # print a nested module > ``` | File | When to Read | What It Covers | | ----------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------- | | `references/crud-ui.md` | C2 list/detail/form product screens | State coverage (loading/empty/error/permission), forms, objective UX gates | | `references/anti-slop.md` | New components or UI redesign | 2026 AI slop patterns, Korean slop, oversized text, fake assets, default UI smells | | `references/aesthetics.md` | Implementing an established visual direction | Domain-correct typography, color, composition, serif three-role system, expressive/functional layers, AI-brand grammar | | `references/product-density.md` | Apps, tools, dashboards | Density profiles for landing, consumer app, SaaS, ops, finance, devtools | | `references/asset-requirements.md` | Any public/product/visual surface | Required screenshots, images, diagrams, charts, generated bitmaps, or 3D assets, mockup production pipeline | | `references/visual-verification.md` | Changes affecting rendered layout | Screenshot, viewport, text fit, state, asset, and motion verification | | `references/korea-2026.md` | Korean-first or Korea-facing UI | Korean service patterns, CJK typography, formats, mobile flows, Korean serif/myeongjo display | | `references/ux-writing-ko.md` | Korean UI copy | Natural Korean labels, error messages, tone, spacing, punctuation | | `references/soft-3d-asset-gates.md` | 3D/miniature/character-like visuals | Toss-style soft 3D vs generic cute asset slop, domain gates | | `references/motion.md` | Motion/animation needed | CSS animations, Framer Motion, CSS scroll-driven timelines, pointer-proximity chip motion (magnetic/dock), View Transitions, domain gates, organic bg + capsule label, product-led hero motion | | `references/liquid-glass.md` | Translucent materials, glass chrome, pill-chip surfaces | Liquid Glass layer discipline, named material states (pill-at-top/pill-scrolled/media-overlay/clear), FE-PILL-NEST-01, blur-free pill alternative, perf + a11y gates | | `references/top-bar.md` | Top/nav bar composition, sticky chrome | Top-bar grammar: geometry, slots, scroll-state contract (FE-TOPBAR-STATE-01), hover-surface contract (FE-TOPBAR-HOVER-01), domain gate, mobile collapse | | `references/iterative-design.md` | Multi-round design | LLM convergence problem, Diverge→Kill→Mutate process, upgrade techniques | | `references/prototype-variants.md` | Runnable design variants | `?variant=` switchers, structurally distinct options, cleanup after winner selection | | `references/typography-wrapping.md` | Heading/descriptor text changes | `text-wrap: balance/pretty`, natural phrase breaks at any width, dynamic-viewport verification, `ch` units, Korean keep-all/orphan rules (verified 2026-07-07) | | `references/logo-sections.md` | Integration/partner logo display | Marquee CSS, static grid, orphan cell fix, grayscale treatment, no individual hover | | `references/brand-asset-sourcing.md` | Brand logos in UI | Simple Icons/SVGL sourcing, AI agent strategy, placeholder hierarchy, legal guide | | `references/reference-capture.md` | Cloning/analyzing other sites | HTML+asset capture mechanics (pageAssets/curl), analysis-only legal line, provenance manifest, never-ship gate | | `references/section-level-sourcing.md` | Section-level design work (hero, pricing, testimonials, etc.) | Per-section-type reference sources from Land-book, One Page Love, and Lapa.ninja | | `../ima2-uiux/references/compositional-patterns.md` | Implementing an award-informed composition | Canonical hero, navigation, motion, and content-structure patterns with implementation gates | | `../ima2-uiux/references/design-award-sources.md` | Sourcing real-world design references | Tiered award/gallery source guide and search tactics | | `../ima2-uiux/references/design-trends.md` | Implementing a dated trend or checking whether a technique is stable | 2026-07-14 prevalence, maturity, signature status, risks, and re-crawl rules | | `references/dropdown-layer.md` | Dropdowns, selects, menus, pickers | Unified dropdown design layer (FE-DROPDOWN-LAYER-01): one skin over headless primitives, DS-detection precedence, scope table, mobile sheet | | `references/layout-discipline.md` | Landing/marketing pages | Hero, eyebrow, section repetition, bento, zigzag, per-section responsive transforms, hero composition grammar (2026) | | `references/consistency-locks.md` | Any multi-section page | Color, shape, theme consistency per page | | `references/responsive-viewport.md` | Layout or breakpoint changes | Canonical breakpoints, page containment, container queries, responsive images, safe area, split-screen | | `references/mobile-ux.md` | Consumer/landing pages with mobile traffic | Thumb zone, touch targets, sticky CTA, mobile section composition, bottom sheet, portrait media | | `references/seo-baseline.md` | Public-facing sites, SSR/SSG | SEO meta, JSON-LD, robots.txt, GEO strategies, OG/Twitter cards | | `references/a11y-patterns.md` | Interactive widgets, modals, forms | ARIA patterns, focus management, keyboard nav, screen reader testing | | `references/performance-budget.md` | Launch / audit | CWV targets, bundle budgets, font loading, image optimization, build gates | | `references/theme-switching.md` | Dark mode / theme | CSS custom properties toggle, FOWT prevention, transition, component checklist | | `references/color-system.md` | Color tokens, palettes wiring, theme-ready CSS | Token layering, `oklch()` + fallback discipline, `color-mix()`, `light-dark()`, Tailwind v4/shadcn wiring, contrast gates (verified 2026-07-07) | | `references/i18n-global.md` | Multi-language / RTL | RTL layout, pluralization, Intl API, locale switching, content expansion | | See also: `ima2-uiux` skill | Vague requests, onboarding, UX states | Intent discovery, design isms, product personalities, onboarding/empty/error patterns | | `references/stacks/react.md` | React projects | Server Components, hooks, state, TanStack Query, shadcn/ui, performance | | `references/stacks/nextjs.md` | Next.js projects | App Router, RSC, image optimization, data fetching, middleware | | `references/stacks/vanilla.md` | HTML+CSS+JS (no framework) | Zero-dependency, viewport fitting, responsive CSS, progressive enhancement | | `references/stacks/svelte.md` | Svelte/SvelteKit projects | Svelte 5 Runes, SvelteKit 2 routing/actions, snippets, migration from Svelte 4 | | `references/stacks/mobile-native.md` | Native mobile app development | RN/Expo current pairing, Flutter 3.44, KMP, Swift 6, framework selection | | `references/stacks/astro.md` | Astro projects | Islands architecture, multi-framework shell, content collections, SSG/SSR/hybrid | Start with `anti-slop.md`, `aesthetics.md`, `responsive-viewport.md`, and `visual-verification.md`. Add domain/locale/stack references only when relevant. For C2 ordinary app screens (form/table/list/detail), `crud-ui.md` alone suffices; add the style references above for marketing/visual surfaces or C3+ work. When frontend choices depend on current framework, design-system, browser API, library behavior, browser-rendered source evidence, or package/source freshness, read the active `search` skill and follow its source-fetch and evidence-status rules before treating external material as proof. ### Verification grounding **STRICT:** For render/executable artifacts (HTML, SVG, games, UI, charts), run the real renderer: headless browser, screenshot, canvas check, or equivalent. Observe the actual output yourself, fix what observation reveals, then re-run. Static parsing confirms well-formed files; it does not prove the artifact is visually or interactively correct. One clean observation is enough for unchanged state; do not re-render unchanged output just to repeat evidence. --- ## 0. Frontend Routing Before designing or coding, classify the work: | Decision | Options | Why It Matters | | --- | --- | --- | | Product surface | landing, app, dashboard, AI tool, public service, education, game, creative | Sets density, typography scale, asset requirements | | Locale | Korean-first, global/i18n, English-only | Sets CJK typography, copy, date/number formats | | Density | campaign, consumer app, productivity, SaaS, ops, finance, developer console | Prevents landing-page composition inside repeated-work tools | | Asset need | none, screenshot, product photo, diagram, chart, illustration, soft 3D, game asset | Prevents asset-free gradient/card UI | | Soft 3D/character gate | not allowed, subtle, primary | Prevents generic cute 3D/mascot slop | | Motion intensity | static, feedback-only, expressive, cinematic | Prevents cinematic motion in utility workflows | Default rules: - For apps/tools/dashboards, build the actual working surface first, not a marketing hero. - For Korean-first work, read `korea-2026.md` and `ux-writing-ko.md`. - For any soft 3D miniature, mascot, chibi, toy-like object, or character-like asset, read `soft-3d-asset-gates.md`. - For product/brand/object/place/person pages, use concrete visual assets in the first viewport. - For finance, government, B2B, admin, auth, security, and developer tools, keep visual warmth restrained and subordinate to clarity. - Every user-facing decision point must justify its existence — defaults first, one primary action per screen, choices demoted to progressive disclosure (`ima2-uiux` UX-LAZY-01 owns the gate). - For text-heavy surfaces (landing, marketing, editorial, public service), apply typography wrapping defaults — see `typography-wrapping.md`. Dashboard table cells are excluded. --- ## 1. Component Identification When the user describes UI in vague terms (e.g. "접히는 거", "팝업 같은 거"): 1. Recommend the best-fit component with reasoning: `<Name> — <what it does, why it fits>` 2. Confirm, then proceed If the user already names a specific component, skip this step. Reference: [component.gallery/components](https://component.gallery/components/) For new React/Vue/Svelte/Next UI source files, prefer `.tsx` or typed component files when the repo supports TypeScript. Inherit `dev` TypeScript strict-compatibility rules. If frontend structure is unclear, read existing source-of-truth docs first, then document pages, components, routes, state stores, and build commands in the repo's existing docs before broad implementation. --- ## 1.5 Objective Gates vs Style Samples Two different kinds of rules live in this skill (see the work classifier): - **Objective UX gates (STRICT/DEFAULT)** — accessibility baseline (§7, §11), state coverage (loading/empty/error/permission), keyboard operability, visible focus, contrast. Missing these are review findings. - **Style direction (STYLE_SAMPLE)** — design direction intake (§2), aesthetics, density profiles, product personalities, preset tokens, and the concrete values in §4-§5 (palettes, font choices, pixel max-widths). These illustrate acceptable choices; they are NOT requirements, must not override an existing design system (Design System Detection stays MANDATORY), and must never be enforced as universal taste (UX-STYLE-01). ## 2. Design Direction Intake > When the user cannot articulate a clear design direction, load `ima2-uiux` to > discover intent and choose a direction before implementing here. Before coding, commit to a domain-correct direction: - **Purpose**: What problem does this interface solve? Who uses it? - **Surface**: Is this a working tool, dashboard, public service, AI workflow, game, landing page, or editorial surface? - **Tone**: Pick a specific direction. For product tools this often means quiet, dense, trustworthy, and fast rather than loud. - **Constraints**: Framework, performance budget, accessibility requirements. - **Signature**: What ONE thing will make this unforgettable? (the signature moment; supporting scroll reveals may exist alongside it per `motion.md` FE-MOTION-BUCKET-01) When user intent is vague ("깔끔하게", "모던하게", "just make it look good"), read the `ima2-uiux` skill and run the User Intent Discovery Protocol before making routing decisions. If the user cannot answer these questions, use the `ima2-uiux` skill's structured preference elicitation flow. Offer product references ("Notion 느낌? Linear 느낌?") and visual comparisons. **Concept pass before code (stub — canonical: `ima2-uiux` §2.5 UX-CONCEPT-GEN-01):** for a C2+ new/redesigned expressive or brand-visible surface (page, hero, key chrome like a top bar) with open design direction — probe `ima2 status`, attempt `ima2 serve` if down, then run `ima2 models --kind image` and configure `ima2 defaults set image <lane>/<model>` before any bare `ima2 gen`; use the native image generator only as a true fallback — then generate 5 highly specific candidate mockups of ONE locked concept, then SYNTHESIZE the best elements across all 5 (NOT pick a single winner) into DESIGN.md and implement from that synthesis — do not start coding the layout blind. Intentionality over intensity. Bold maximalism, refined minimalism, dense utility, and friendly consumer UI can all work when they match the domain. --- ## 3. Baseline Configuration Adjust these dials based on what's being built. Present to user if unclear. | Dial | Default | Range | Meaning | | ---------------- | :-----: | :---: | ------------------------------------ | | DESIGN_VARIANCE | 5 | 1-10 | 1=symmetric utility, 10=asymmetric art | | MOTION_INTENSITY | 4 | 1-10 | 1=static, 10=cinematic choreography | | VISUAL_DENSITY | 5 | 1-10 | 1=art gallery airy, 10=cockpit dense | After Design Read, set dials per `ima2-uiux` §2 Dial Setting. Product density profile (D1-D8 in `references/product-density.md`) sets component class; VISUAL_DENSITY (1-10) sets spacing within that class. These are orthogonal axes. Adapt dynamically based on user requests. Dashboard → density up. Portfolio → variance up. Data tool → motion down. Korean app/tool surfaces usually need higher density and clearer hierarchy, not oversized hero text. --- ## 4. Implementation Read `references/aesthetics.md` for full guidelines. Summary: