diff --git a/skills/frontend-app-builder/SKILL.md b/skills/frontend-app-builder/SKILL.md index b350dd8..5285284 100644 --- a/skills/frontend-app-builder/SKILL.md +++ b/skills/frontend-app-builder/SKILL.md @@ -1,205 +1,145 @@ --- name: frontend-app-builder -description: Use for new frontend applications, dashboards, games, creative websites, hero sections, and visually driven UI from scratch, or when the user explicitly asks for a redesign/restyle/modernization. Builds from high-taste image-generated concept design with faithful implementation and browser testing. +description: Use for new frontend applications, dashboards, games, creative websites, hero sections, and visually driven UI from scratch, or when the user explicitly asks for a redesign/restyle/modernization. Builds from clean, airy, high-taste image-generated concept design with faithful implementation and browser testing. --- # Frontend App Builder -Use this skill to turn a frontend application request into a working, visually checked app. For new apps, dashboards, games, websites, product interfaces, tools, redesigns, and other visually driven UI work from scratch, act first as a senior front-end designer unless the user explicitly says not to use Image Gen for concepting: create a concrete visual direction, use the installed @imagegen skill to produce an overall interface, screen, dashboard, game, website, or hero concept, then implement the concept in code as faithfully as possible. Aim for high-taste, agency-quality, minimal design rather than maximal visual spectacle, except when the product or game genre calls for richer art direction. Use additional generated assets when they materially improve the implemented UI or are needed to match the generated concept. For app interfaces, implement the main functionality with believable local state and real interactions so the user can click through the core idea instead of only viewing a static mockup. The accepted concept is an implementation contract, not a moodboard: do not redesign, simplify, rename, reorder, or substitute it unless the user explicitly asks for a change. Keep working until the running app matches the generated concept closely enough to pass a professional design-agency inspection and the core workflow has been verified, or until you hit a concrete blocker that you report clearly. Always run the app and verify the result in a browser; use the Browser plugin / built-in app browser first whenever it is available, and only fall back to Playwright with Chromium when Browser/IAB is unavailable or demonstrably unreliable for the needed check. +Use this skill to create polished frontend apps, dashboards, games, creative websites, hero sections, redesigns, and other visually driven UI. Act first as a senior front-end designer, then as an engineer implementing an approved design spec. -## Workflow +## Core Standard -1. Read the existing app structure, scripts, styling system, and asset locations before editing. -2. Use a concept-first image generation pass for new apps, dashboards, games, websites, product interfaces, tools, redesigns, and visually described UI from scratch unless the user explicitly instructs you not to use Image Gen for concepting. -3. If the user asks to generate a concept first, review concepts, or hold implementation until approval, enter Concept Review Mode: generate and show the concept, iterate with the user until they are happy, and do not implement yet. -4. For concept-first implementation work, read and follow the installed @imagegen skill, then write a concise design-director brief and generate the overall app, dashboard, game, website, screen, redesign, or hero concept before implementation. -5. Choose one generated image as the accepted layout concept and keep its exact path visible in your notes. If multiple images were generated, label the rest as supporting assets and do not let them redefine the page structure. -6. Reject or iterate on generated concepts that are cluttered, overly decorative, under-specified, or trying to show too many product ideas at once. -7. Before coding, create a concept-to-implementation inventory from the accepted concept: native concept size/aspect, first-viewport composition, headline line breaks, nav/header geometry, brand mark, palette, type scale, panel/card topology, row counts, chart axes, drawers/rails, footer/status regions, asset roles, data/copy values, visible control states, and mobile continuation. -8. Define the minimum implementation plan, core interaction path, and asset list needed for the complete screen, page, or flow. Every visible concept element should map to code, an imagegen asset, or a clearly named intentional deviation. -9. If the accepted concept only shows part of the page or a single state, infer the remaining sections, states, and responsive views from the concept's visual language and implement them in the same design system. -10. Use the imagegen built-in tool path for missing visual assets such as logos, brand marks, hero imagery, product scenes, illustrations, textures, mockups, thumbnails, and empty-state art. -11. Treat the accepted concept as the visual spec. Extract layout, spacing, typography, palette, imagery, component shapes, interaction model, and responsive implications before coding. -12. Complete the inline preservation checklist below before coding; map every visible concept element to an implementation choice. -13. Implement the design in the app using the repo's existing framework, routing, component, styling, state, data, accessibility, and asset conventions. -14. Use imagegen again for individual project assets only to reproduce or isolate assets from the accepted concept, not to invent a new direction. -15. Add the main app functionality, thoughtful motion, and interactive visual behavior for concept elements that should feel alive, demonstrate the product, or reward exploration. -16. Run the app and use the Browser plugin / built-in app browser first for visual fidelity and interaction testing. If Browser/IAB is unavailable, cannot reach the local app, cannot capture the needed view, or produces unreliable screenshots such as broken fixed-header stitching, use Playwright with Chromium and record the fallback reason. -17. Perform an agency pass before final: compare the running UI against the accepted concept at the concept's native aspect/size when practical, a normal desktop viewport, and a mobile viewport. Name at least five concrete mismatches and fix them, or explicitly state that no material mismatches remain. Structural mismatches in topology, branding, copy, density, media behavior, or primary workflow block completion. -18. Verify the core workflow through the browser. Visible controls, media players, filters, forms, tabs, drawers, command palettes, canvas/game controls, and generated-result demos must update real local UI state; do not ship fake timecodes, inert buttons, hidden underlying media, or placeholder interactions. -19. Fix every material mismatch found during browser testing, then repeat the browser check. Keep iterating until the running app matches the concept and works as a product surface or a real blocker prevents further progress. -20. Do not send the final response or write any user-requested completion marker until the fidelity gate has passed with concrete evidence: accepted concept path, Browser/IAB verification method or Playwright fallback reason, mismatch list, fixes or blockers, and core workflow proof. -21. Before finishing, remove temporary QA-only files such as browser screenshots, fidelity reports, scratch notes, and intermediate generated assets unless the user explicitly asks to keep them or the task contract explicitly requires them. The accepted concept image may remain available for design iteration, and final assets used by the implementation must remain in the project's normal asset location. +The two priorities of this skill outrank everything else: -## Imagegen Coordination +1. Create a great-looking Image Gen design first: clean, airy, distinctive, complete, and not repetitive by default. +2. Do not stop until the accepted design and browser implementation match 10/10. Keep fixing visual, interaction, responsive, asset, and typography mismatches until `view_image` comparison would pass agency sign-off. -- The installed @imagegen skill is the source of truth for image generation and editing mechanics. Use its built-in tool mode by default; never choose its CLI fallback unless the user explicitly asks for CLI mode. -- Every Image Gen concept prompt for a website, landing page, dashboard, product interface, app, tool, or game UI should explicitly ask for a clean interface that embraces whitespace, uses restrained content density, and avoids clutter unless the genre or user request calls for intentional density. Do not ask Image Gen to fill the page with extra cards, stats, badges, charts, icons, HUD elements, controls, or sections unless the user explicitly requests them or the game/product needs them. -- Classify new full-page, dashboard, app, game UI, and section concepts as `ui-mockup` unless another imagegen taxonomy slug is clearly more precise. For redesigns, use `ui-mockup` when the screenshot is only a reference, or an edit slug such as `style-transfer` when the screenshot is the imagegen edit target. -- Treat initial website concepts as preview or design-reference outputs, but do not lose track of the accepted concept. For concept-first implementation, keep the accepted concept reopenable by exact path. Do not copy it into project docs or audit folders unless the user asks or the final deliverable explicitly needs that artifact. -- When multiple images are generated, explicitly separate roles: one `accepted layout concept` controls the UI structure, while later hero photos, product renders, textures, thumbnails, or illustrations are `supporting assets`. Supporting assets may fill slots in the accepted concept; they must not replace the accepted concept's layout, section order, density, palette, or first viewport. -- For assets referenced by code, follow imagegen's project-bound rule: copy or move the selected final into the project's normal public/static asset location and reference that workspace path. -- Do not create or keep a generic generated `hero.png` as a token use of ImageGen when it is not central to the rendered page. If a generated asset is not used, remove it before finishing unless it is the accepted concept image kept for user iteration. -- When converting a concept into implementation, use imagegen for all non-icon visual assets that are part of the design: logos, brand marks, hero imagery, product renders, illustrations, textures, thumbnails, posters, avatars, and empty-state art. Do not use SVGs as temporary stand-ins for those assets. -- Icons are the exception: recreate concept icons faithfully as SVG or use the repo's icon system only when it accurately matches the concept. Keep icons accessible and consistent with the implemented UI. -- Do not replace a concept's high-quality asset with a rough CSS drawing, flat gradient, generic stock-like crop, stretched raster, or placeholder SVG. If the concept depends on a map, poster wall, character, product pack, hero photo, furniture/material image, food/drink image, chart backdrop, or brand mark, use imagegen or a faithful crop/edit to supply that visual quality. -- For website-specific prompt scaffolding, use `references/imagegen-website-concepts.md`. +## Hard Rules -## Concept-First Image Generation +1. Use Image Gen for the visual concept unless the user explicitly opts out or the task is a small UI fix inside an existing design system. +2. Design the complete requested surface before coding. For a full page, app, dashboard, game, or product interface, a header or hero concept is not enough. For multi-section websites and long landing pages, prefer coordinated section-by-section concepts, plus an optional overview for rhythm, over one tall image that loses detail. For apps, dashboards, games, or compact product surfaces, generate the full primary screen plus any needed state, responsive, or asset concepts first. +3. In Plan mode, generate the design first, then use `request_user_input` to get design approval before planning implementation details. +4. Once accepted, the concept is a production design spec. No creative liberties during implementation: do not reinterpret layout, visible copy, hierarchy, container model, styling, imagery, density, or sections unless the user approves it or a concrete blocker requires it. General design heuristics never override the accepted concept. +5. The completion bar is agency-signoff faithful implementation: 10/10 fidelity to the accepted spec plus production-quality code. If the browser-rendered UI would receive design-review comments, keep fixing it. +6. Before coding, build a small design system from the accepted image: tokens, typography, component families, variants, spacing, icon treatment, and container rules. Include both content typography and UI chrome typography for tools, editors, and dashboards. Implement from that system so repeated elements stay consistent. +7. Hero eyebrow, kicker, pretitle, badge, or pill labels above the main heading are prohibited by default. Use one only when the user explicitly requested it or the accepted/reference design already contains it. +8. Verify in the Browser plugin / built-in browser first. Use Playwright Chromium only when Browser/IAB is unavailable or unreliable, and state the fallback reason. +9. Final handoff is blocked until you use `view_image` on both the accepted concept and the latest browser screenshot. This cannot be skipped or replaced with browser inspection alone. Judge the pair directly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If not, keep fixing. +10. Remove temporary QA artifacts before handoff unless the user or task explicitly asks to keep them. -Use image generation before implementation for these requests unless the user explicitly opts out: +## Image Gen Workflow -- A new app, dashboard, product interface, tool, game UI, or website from scratch with no existing visual design to work from. -- A new creative website, landing page, microsite, product page, portfolio, marketing page, or visually distinctive app surface. -- A new dashboard or operational interface where the information architecture, density, visual hierarchy, and data presentation need a first visual direction. -- A new game, simulation, or playful interactive interface where the art direction, HUD, board, scene, controls, or primary play surface needs a first visual direction. -- A redesign, refresh, restyle, or modernization of an existing website or app. -- A beautiful hero section, above-the-fold treatment, immersive first screen, or other section described mainly in visual terms. -- A recreation or adaptation of a specific UI style, visual reference, aesthetic, brand mood, or layout direction. -- A request where the visual system is under-specified and a strong concept would reduce ambiguity before coding. +Read and follow the installed @imagegen skill. For website-specific briefing guidance, use `references/imagegen-website-concepts.md`. -Do not force concept generation for small UI fixes, routine forms, admin panels, straightforward CRUD screens, or tasks where the existing design system already dictates the answer. Do not use concept art when the user asks you to copy an existing design/codebase, extend an existing design, or implement within provided art/design constraints. If the user explicitly says not to use Image Gen for concepting, skip the concept step and work within the provided or existing design direction. +Before calling Image Gen: -For redesigns, first capture or use the existing site/app screenshot when possible. Use that screenshot as input for the image-generation/editing pass so the concept preserves the real information architecture and improves the visual treatment instead of inventing an unrelated page. +- Copy the user's concrete requirements into the brief: product/page purpose, audience, required sections or states, workflow, supplied copy, nav labels, CTA labels, data fields, required media, responsive needs, and implementation constraints. +- Ask for the complete requested surface: full page, app screen, dashboard, game screen, or coordinated section/state set. If the deliverable is more than a hero, say the concept must include downstream sections, states, or responsive continuation. +- Repeat the implementation constraints: code-native app UI text and controls, fully rendered product/background assets with their own text and branding when appropriate, separable assets, reusable component families, intentional container model, no default card grids, no invented hero eyebrows/kickers/badges/pills, and practical HTML/CSS/component implementation. +- Preserve information architecture from user content, screenshots, or existing apps. Do not let Image Gen invent unrelated sections, fake metrics, new product claims, extra dashboards, new navigation, or a different product story. +- For multi-section websites or long landing pages, default to one coordinated concept image per major section when a single image would cram detail or flatten the layout. Keep one `accepted layout concept` responsible for structure and rhythm; treat later images as supporting section, state, responsive, or asset specs. +- For games, plan a dedicated Image Gen asset pass in addition to the concept: transparent character/state sprites or sprite sheet, terrain/platform tiles, collectibles, hazards, goal/checkpoint objects, props, and 2-3 parallax/background layers when the environment has depth. HUD text, scoring, controls, physics, and collision remain code-native. -Treat the generated concept as a design reference, not as a shippable asset. Implement the layout, spacing, color, typography, hierarchy, and interaction affordances in code. Do not ship a static screenshot of the generated page as the actual UI. +Reject or iterate on concepts that are header-only for a full-surface ask, cluttered, generic, repetitive, under-specified, unreadable, over-decorated, off-spec with hero eyebrows/kickers/badges/pills not explicitly requested or present in the reference, or not practical to implement faithfully. + +## Design Quality Bar + +The concept should look like a professional product mockup by a senior product designer: + +- One clear creative idea or visual point of view. +- Strong first viewport with clear offer, product signal, and primary action. +- Full-page rhythm: sections, states, transitions, and mobile views feel designed as one system, without repetitive card stacks or repeated section formulas. +- Excellent typography: clear hierarchy, scale, weight, line height, label treatment, and control/chrome text that never falls back to browser-default sizing. +- Intentional whitespace and density; no filler cards, hero eyebrow/kicker labels, pills, badges, fake metrics, or icon rows unless explicitly requested or present in the accepted design. +- Coherent visual system: palette, spacing, radius, borders, shadows, gradients, icon style, imagery, and component geometry. +- High-quality generated assets for logos, brand marks, hero imagery, product renders, background scenes, illustrations, textures, posters, avatars, empty states, and game sprites/tiles/background layers. Product/background assets should be fully rendered with consistent branding and in-image text when that text belongs to the asset. +- Purposeful motion that clarifies hierarchy, reveals state, or makes the product feel tangible. +- Specific, non-generic copy when the user has not provided exact copy. + +Default to clean, airy, tasteful 7/10 creativity: distinctive enough to feel designed, restrained enough to build, and not repetitive. Interpret "clean" as edited and legible, not empty or sterile. ## Concept Review Mode -Use this mode only when the user explicitly asks to generate a concept ahead of time, review concept options, or wait for approval before implementation. +Use only when the user asks to generate concepts first, review options, or wait for approval. -- Generate the concept with Image Gen and show it to the user. -- Iterate with the user on the concept until they are happy. -- Do not implement code while the user is still reviewing the concept. -- When the user approves the concept or asks you to implement it, treat that approved concept as the active spec and enter the strict Concept Fidelity workflow. -- After implementation starts, faithfully implement the approved concept to the T. Run the app and verify in the Browser plugin / built-in app browser first. Use Playwright with Chromium only when Browser/IAB is unavailable or unreliable for the needed check, and state the fallback reason. Keep iterating before completion until the running UI matches the approved concept or a concrete blocker is reported. +- Generate and show the concept. +- Iterate until the user approves. +- Do not implement while the user is still reviewing. +- Once approved, treat the concept as the active spec and follow the fidelity workflow below. -## Concept Fidelity +## Before Coding -- Once a concept is accepted, follow it closely enough to pass inspection from the designer who created it. The implementation should be a faithful coded version of the generated design, not a loose reinterpretation or a simpler page inspired by it. -- If you generated a concept because the user asked or because this skill required concept-first work, you must adhere to what was designed. Treat that concept as the active spec until the user changes it. -- Persistence is mandatory. Do not stop at a partial implementation, a first draft, a build that merely compiles, or a page that only captures the general vibe. Continue implementing, comparing, and refining until the browser-rendered UI matches the concept's actual structure, visual details, and expected interaction model. -- Preserve the concept's visible content and information architecture by default: headline text, emphasized words, navigation items, CTA labels, proof points, section titles, section order, brand mark, first-viewport composition, and the next-section preview. -- If the concept does not contain the full contents of the requested page, continue the rest of the page in the same design language: same spacing rhythm, type scale, palette, imagery style, component geometry, and interaction model. The hidden or downstream parts should feel designed by the same system, not appended from a generic template. -- Preserve the concept's mock state unless the user asks for live data. Clone-like and product surfaces often need designed sample repositories, issues, videos, incidents, events, rows, files, and copy; replacing those with live API output or generic filler can make the implementation less faithful. -- Do not replace the concept with a brand-first, simplified, darker, heavier, or otherwise reinterpreted version because it seems easier to implement. If a change seems necessary, call it out as a deviation and minimize it. -- Before coding, translate the concept into a concrete implementation checklist: grid structure, section order, alignment, whitespace, type scale, font personality, color tokens, borders, radii, shadows, image crops, button treatments, visual effects, motion opportunities, and key responsive behavior. -- Recreate visual assets from the concept when needed. If a logo, brand mark, hero image, product mockup, texture, cutout, poster, avatar, or illustration is central to the concept, use imagegen to create that asset as accurately as possible, then store the selected final in the project asset path. -- Do not generate a second unrelated hero or product image that competes with or replaces the accepted concept. Additional imagegen work must be constrained to matching the concept's subject, composition, crop, lighting, palette, and role in the layout. -- Do not use "code-native" as an excuse to drop visual structure. Code-native implementation means recreating the concept with HTML/CSS/components where appropriate; it does not permit deleting dashboards, sidebars, tables, drawers, workflow diagrams, HUDs, media rails, illustration style, or first-viewport density. -- Usability and responsive fixes must preserve the concept's information architecture. Tune spacing, wrapping, typography, and overflow before replacing tables with cards, removing columns, switching dark to light, moving key modules below the fold, or changing the primary interaction model. -- Keep code-native UI code-native. Text, navigation, buttons, forms, cards, layout, and controls should be implemented in HTML/CSS/components, while raster assets supply imagery that cannot be cleanly built in code. -- Use browser inspection or screenshots as the fidelity check. Compare the running implementation against the concept for composition, hierarchy, spacing, typography, color, asset framing, and visible interaction states. -- No silent fidelity pass is acceptable. After browser verification, name the material mismatches you see. If there are no material mismatches, state that explicitly with the concept path and verification method. If exact fidelity is impossible because of accessibility, responsiveness, missing assets, or framework constraints, preserve the design intent, minimize the deviation, and state the exact blocker. Do not present an avoidable mismatch as complete. -- Do not leave fidelity reports, screenshots, comparison images, or other QA-only artifacts in the final workspace unless the user or benchmark explicitly requires them. If temporary screenshots were written during verification, remove them before handoff. +Turn the accepted concept into a design system and implementation inventory before coding: -## Mandatory Preservation Checklist +- Exact visible copy, nav items, CTA labels, section headings, proof points, data labels, and important UI text. +- Allowed above-the-fold copy list: every visible hero, nav, eyebrow/kicker/pretitle, badge/pill, CTA, label, and proof string allowed from the accepted concept or user-provided copy. +- First viewport composition, section order, downstream states, responsive continuation, and next-section preview. +- Brand mark, imagery roles, product mockups, dashboards, tables, charts, maps, media rails, forms, HUDs, or other visual artifacts. +- Standalone asset needs: if the concept includes a logo, brand mark, product label, packaging, poster, sign, product render, or branded background object, create matching standalone assets with Image Gen editing before implementation so branding stays coherent. +- Game asset needs: if the concept is a game, create matching production art assets with Image Gen before implementation. Include transparent sprite/state assets, tiles/platforms, collectibles, hazards, goal objects, props, and parallax/background layers as needed; use code for collision boxes and game state, not as a substitute for visible art. +- Design tokens sampled or approximated from the image: background, surface, text, muted text, border, shadow, accent, semantic colors, radii, elevation, spacing scale, and motion timing. +- Typography system: font family/fallback, type scale, weights, line heights, tracking, label treatment, heading/body/caption styles, control text styles, and responsive type behavior. +- Component families and variants: buttons, navigation, rows, panels, media frames, product mockups, cards only where present, tables, forms, chips, icons, empty states, responsive variants, hover/focus/selected states. +- Container model: cards, panels, rails, bands, lists, tables, canvases, drawers, sidebars, modals, or full-bleed sections. +- Core workflow: controls that must respond, selected states, filters, tabs, edits, creation flow, success state, playback, game controls, or generated-result demo. -Before coding a concept-first build, extract and preserve: - -- Exact visible copy: headline, highlighted words, eyebrow, body copy, labels, CTA text, proof points, section headings, and important UI labels. -- Navigation and actions: all nav items, dropdown indicators, login/sign-in links, primary and secondary CTAs, and their relative placement. -- Brand system: logo shape, wordmark treatment, accent colors, icon style, visual motif, and any distinctive brand mark. -- First viewport: hero layout, primary visual composition, text block location, CTA group, proof points, hero asset framing, background treatment, and whether the next section is visible. -- Section structure: section order, section count, light/dark transitions, cards, dashboards, feature rows, demo panels, and footer/status elements visible in the concept. -- Continuation plan: if the concept stops before the requested full page or flow is complete, list the downstream sections, states, and responsive surfaces you will add in the same design language. -- Visual system: typography style, type scale, spacing density, radius, borders, shadows, texture, color mood, contrast, and overall weight. -- Product visuals: dashboards, cards, charts, maps, nodes, device frames, topology scenes, 3D objects, or other visual artifacts that need assets, code-native UI, animation, or simulated interaction. -- Functional surface: the primary user journey, controls that must respond, state changes the user should see, and any real underlying media/data that must not be faked. -- Responsive intent: what must remain visually recognizable on desktop and mobile. - -Before finishing a concept-first build, compare the concept and running browser-rendered UI side by side, using transient screenshots when that is the clearest way to inspect. Do not claim fidelity until these match materially: copy and emphasis, nav and CTA labels, brand mark, hero composition, first-viewport balance, next-section visibility, section order, section types, proof points, product/demo elements, palette, typography, spacing, borders, radii, visual weight, motion, and simulated interactions. If they do not match, keep working: adjust code, regenerate or crop assets, tune spacing and typography, rerun the app, and compare again. - -## Fidelity Gates By Surface - -- Landing pages and company sites: preserve the accepted concept's first viewport, hero image role, brand/nav/CTA labels, section order, next-section preview, and any signature physical objects or photography. If the concept does not show the entire page, build the remaining sections in the same visual system without altering the above-the-fold composition. -- SaaS product pages and branded product websites: preserve the product mockup inventory, workflow diagram, feature strip, trust/proof elements, exact brand treatment, and first-viewport balance. Do not replace a diagram or dense product mockup with a generic floating card because it is easier to code. -- Operational dashboards and app interfaces: preserve density, panel topology, sidebars, headers, tables, drawers, tabs, timelines, charts, maps, columns, row counts, and dark/light palette. Implement the main workflow with clickable controls, local state changes, selection/detail behavior, filters, modes, or edits as appropriate. A dashboard concept that is table-driven must not become a card grid unless the concept already shows cards. -- Timeline, planner, scheduling, and ops tools: preserve the grid/time-axis anatomy, row spans, event density, status rails, active service/shift selectors, and first-viewport command-center fit. Do not push the main operational surface below the fold when the concept shows it immediately. -- Clone-like interfaces: preserve the recognizable skeleton before adding polish. For GitHub-like, Linear-like, YouTube-like, or similar requests, do not add marketing heroes, oversized stat cards, or custom navigation that make the result stop reading as the requested product type. -- Games and playful tools: preserve the art direction, world materials, character/sprite treatment, HUD framing, primary play surface, controls, and reward/hazard visuals. If CSS shapes cannot match the concept's illustration quality, generate or crop game assets that do. -- Games must pass a playability gate, not just a screenshot gate: scripted keyboard/pointer interaction should verify movement, jump/drag/action behavior, scoring, hazards, restart, and that collision geometry aligns with visible art. -- Media and image-heavy surfaces: preserve the player/poster/thumbnail proportions, right-rail or gallery density, photographic versus illustrated treatment, and primary media asset role. Do not replace a photographic or illustrated concept with a generic SVG poster. -- Media players must operate on the real required media. Do not hide a required video/audio element behind generated overlays except as an initial poster; verify visible media opacity, load state, real duration, play/pause, seek/progress, and that the displayed frame changes. -- Form, booking, purchase, and restaurant surfaces: verify the main transaction path such as reservation, order, inquiry, booking, add item, or save state, including success/confirmation state. -- Product/SaaS mockups: preserve the product mockup inventory: sidebars, inboxes, tables, composer panels, right rails, device frames, workflow diagrams, chips, badges, and status rows. Fix clipping/overflow before final. - -## Motion And Interaction - -- Add motion with the same taste level as the static design: purposeful, polished, and restrained. Use animation to clarify hierarchy, reveal state, direct attention, or make the product feel tangible. -- If the concept includes visual product elements such as dashboards, canvases, timelines, maps, 3D objects, device frames, charts, cards, nodes, or process flows, make the important ones interactive when feasible. A convincing simulated interaction with local state is better than a static prop when it helps explain the product. -- For app interfaces, implement the main user journey rather than only hover polish. Examples include creating or editing an item, switching modes, filtering data, selecting rows to reveal details, dragging or toggling controls, stepping through a workflow, or simulating a generated result with believable local state. -- Prefer subtle page-load choreography, hover/focus states, scroll-linked reveals, animated product previews, live counters, draggable/toggleable controls, or stateful demo panels over decorative motion that does not support the interface. -- Match the motion to the concept's visual language. A calm editorial site should have quiet easing and small transitions; a product demo can have richer animated state changes when they reveal capability. -- Keep interactions accessible: preserve keyboard/focus states, avoid motion that blocks reading, respect `prefers-reduced-motion`, and make sure animation does not cause layout shift or text overlap. -- Treat screenshot timing as part of fidelity. Browser evidence should capture stable UI states: wait for entrance animations to settle, avoid first-load opacity that makes key assets look washed out, eager-load local images needed in screenshots, and disable or bypass nonessential load transforms when they distort comparison. -- Verify motion in the browser, not just in code. Interact with the elements, check timing and polish, and adjust until the behavior feels like a designed part of the concept. - -## UI Quality Principles - -- Great interfaces start with a clear job. Make the primary user goal obvious, reduce competing choices, and keep the visual hierarchy focused on what the user should understand or do next. -- Whitespace is a design material. Use it to create hierarchy, calm, scanability, and confidence. Do not fill empty areas with decorative cards, icons, stats, labels, or filler copy. -- Content density should be intentional. Default to fewer, stronger messages and components; add density only when the product surface genuinely requires comparison, monitoring, or repeated operational use. -- Strong landing pages make the offer legible in the first viewport: clear headline, supporting copy, one primary action, one optional secondary action, and a concrete product or brand signal. Show proof only where it reinforces trust without stealing focus. -- Great product interfaces feel useful, not decorative. Prioritize real workflows, clear affordances, meaningful states, readable data, responsive controls, and helpful empty/loading/error states. -- Use progressive disclosure. Put advanced details, secondary proof, and supporting features after the primary story or behind interactions instead of cramming everything above the fold. -- Good visual systems are coherent: consistent spacing, type scale, radius, border, shadow, icon treatment, and color roles. Use contrast and accent color sparingly to guide attention. -- UI imagery should clarify the product, customer, workflow, or atmosphere. Avoid generic visual noise and avoid images that look impressive but do not explain or support the page. -- For apps and product demos, make the interface feel live with believable sample data and lightweight interaction, but keep it subordinate to the core task and design hierarchy. -- Respect accessibility and usability as part of taste: readable text, sufficient contrast, clear focus states, target sizes, responsive layout, and reduced-motion support. - -## Taste Bar - -- Default to restraint. The concept should look like it came from a strong digital product agency: confident hierarchy, generous whitespace, a small number of excellent elements, and no filler. -- Prefer one clear focal idea per viewport. A refined hero with one strong composition is better than multiple competing dashboards, floating panels, stats strips, icon rows, and feature grids. -- Use a restrained palette with one or two meaningful accents. Avoid neon overload, glowing sci-fi interfaces, bokeh/orb decoration, dense grids, and dark cyberpunk dashboards unless the user explicitly asks for that style. -- Keep information density appropriate to the product. SaaS and operational tools can be dense, but still need quiet structure, clear grouping, and breathing room. -- Use typography as a primary design tool: elegant readable sans-serif, occasional editorial serif, or crisp mono accents. Avoid novelty type, excessive all-caps labels, and oversized decorative text treatments. -- If the generated concept looks busy, iterate before coding with a simplification prompt: reduce decorative elements, remove unnecessary cards and badges, calm the palette, clarify the hierarchy, and keep only the elements that support the user's goal. - -## Design Direction - -- Think like a highly skilled front-end web designer giving a clear brief to another designer: define the page purpose, audience, hierarchy, visual mood, layout system, color palette, typography direction, imagery needs, and interaction feel. -- Follow the user's requested style and content priorities, but keep the UI clean and intentional. Avoid extra cards, badges, stats, icons, illustrations, decorative elements, and secondary sections unless they serve the user's goal. -- Prefer elegant, common-but-creative typography choices: refined sans-serif pairings, editorial serif accents, crisp mono details, or expressive display type only when it fits the product. Keep type readable and avoid novelty fonts. -- Use generated concepts to explore the whole composition first. Generate individual assets afterward only when the implementation needs specific logos, brand marks, hero imagery, product renders, textures, illustrations, thumbnails, or empty-state art. -- Keep UI text, labels, navigation, metrics, and controls in code rather than baked into generated images. -- Use concept output to extract implementable decisions: layout grid, spacing rhythm, color tokens, type scale, image treatment, component shapes, and motion/interaction cues. - -## Asset Design - -- Use existing brand or product assets when the user has provided them; otherwise use built-in Codex image generation instead of placeholder gradients, generic SVG decoration, or empty gray boxes. -- Prompt generated concepts and assets with concrete subject, page purpose, style, composition, aspect ratio, background needs, typography direction, density, and intended UI placement. -- Keep UI text, labels, numbers, and controls in code rather than baked into generated images. -- Store generated or edited assets in the project's normal public/static asset location and reference them through the app's existing asset pipeline. -- Prefer assets that reveal the actual product, use case, state, or atmosphere the interface needs to communicate. -- Use imagegen for logos and brand marks unless the user provides an existing vector logo. SVGs are acceptable for icons only, and those icons must faithfully match the concept rather than acting as generic placeholders. +If the concept omits required downstream sections, states, or mobile views, generate matching section/state concepts when visual consistency is uncertain. Otherwise extend in the exact same visual system. ## Implementation - Build the real usable surface first, not a marketing wrapper around a future app. -- Match existing conventions for components, tokens, spacing, routing, state, loading, errors, and empty states. -- Keep implementation quality production-oriented: use semantic markup, accessible controls, typed data structures where the repo supports them, component boundaries that match the existing app, no duplicated one-off logic when a local helper exists, and no hardcoded layout hacks that will collapse under normal responsive or content changes. -- Preserve the accepted concept's visual hierarchy and proportions when mapping it into the repo's component system. -- Implement visible concept elements as working UI whenever practical. If an element looks like a product surface, demo, control, chart, or visualization, give it believable state, hover/focus behavior, or lightweight interaction rather than leaving it as inert decoration. -- For app interfaces, make the primary workflow experiential. The user should be able to click through the main idea, see state update, and understand how the app would work even if the data is local and simulated. -- Keep layouts responsive with stable dimensions for images, toolbars, grids, cards, and controls so generated assets do not cause shifting or overlap. -- Make the generated assets serve the interface: crop, mask, size, and lazy-load them intentionally instead of dropping them in at arbitrary dimensions. -- Supplement implementation with type checks, linting, and unit tests when the repo already uses them. +- Follow the repo's framework, routing, component, styling, state, accessibility, and asset conventions. +- Implement through the design system extracted from the image. Similar elements must use the same component or shared style primitive; differences should be explicit variants, not one-off copied CSS. +- Implement the accepted concept exactly. Preserve copy, hierarchy, section order, density, colors, typography, spacing, radii, borders, shadows, asset framing, and interaction model. +- For multi-section pages, implement in slices that match the accepted section concepts. Start with the first viewport, compare its browser screenshot to the section concept, fix visible drift, then continue section by section. Do not defer all visual comparison until the whole page is coded. +- Do not add new visible above-the-fold copy, hero eyebrows/kickers, explanatory labels, subtitles, or category text after concept acceptance unless it appears in the accepted concept, came from the user, or is recorded as an intentional deviation. If semantic HTML, SEO, or accessibility requires changing an H1 or heading level, change the element semantics first; do not invent compensating visible copy. +- Do not add decorative hero eyebrow labels, pills, badges, gradients, glows, or overlays that were not in the accepted design. Do not substitute a gradient treatment unless it matches the concept's palette, direction, intensity, and placement. +- Define typography on controls deliberately. Do not rely on browser defaults or inherited `16px` sizing for buttons, tabs, inputs, toolbars, sidebars, inspector panels, layer rows, status bars, command palettes, or export/share controls. +- Preserve the container model. Do not add cards, bordered panels, floating containers, tiles, or card grids where the spec uses open whitespace, bands, rails, lists, tables, canvases, or full-bleed composition. +- Keep real interactive app UI text, navigation, buttons, forms, tables, controls, and labels code-native. This does not apply to text and branding that belong inside product images, posters, packaging, signs, background scenes, hero photos, or other raster assets. Do not ship a static screenshot as UI. +- Use Image Gen for central non-icon assets. Render product images and background assets completely with the needed text, logos, marks, labels, packaging, signage, and branding. When the asset must layer into the UI, request a transparent background or clean cutout. Quote exact asset text and require verbatim rendering when text matters. +- If the accepted design includes branded product imagery, use Image Gen editing to create standalone versions of the logo/product/packaging/signage assets from the concept or a matching asset pass. Include transparent-background variants when those assets need to layer into the UI. Do not rebuild branded raster assets from generic CSS, mismatched fonts, or approximate labels. +- For games, use Image Gen for visible production art: character/state sprites or sprite sheets, terrain/platform tiles, collectibles, hazards, goals/checkpoints, foreground props, and parallax/background layers. Do not fall back to canvas-drawn shapes because collision, scaling, or animation is simpler. Keep HUD text, score, controls, hit boxes, physics, and game state code-native, and tune collision geometry to the rendered assets. Any code-drawn or vector game art must be listed as an intentional deviation or concrete blocker. +- Do not replace concept assets with rough CSS drawings, generic gradients, placeholder SVGs, or stock-like crops. Images must sit naturally in the composition: background color, lighting, edges, crop, shadow, and transparency should blend with the surrounding design. SVG is fine for faithful icons and directional glyphs. +- Use SVG/icon components for arrows, chevrons, carets, disclosure indicators, pagination arrows, and carousel arrows; do not use plain text glyphs unless the concept intentionally does. +- Make app interfaces experiential: local state, meaningful selected states, working filters/tabs/forms, editable or creatable items, success states, playback controls, game controls, or simulated generated output where appropriate. +- Use interactive UI inside a hero only when it genuinely fits: SaaS/software product previews, product demos, or purposeful interactive animation. Do not force fake interactive chrome into a branded, editorial, product, venue, food, consumer, or background-led hero. Faithful implementation and consistent branding are more important than adding interactivity. +- Add motion only where it supports the design. Respect accessibility and `prefers-reduced-motion`. +- Keep implementation production-oriented: semantic markup, stable responsive dimensions, no fragile hardcoded hacks, and type/lint/test checks when the repo supports them. -## Browser Testing +## Verification -- Always run the app and verify concept-first work in a browser. Use the Browser plugin and built-in app browser when available. -- Use the Browser plugin / built-in app browser as the default verification surface for localhost apps. Load the page, inspect the first viewport, scroll, click through the main workflow, and use screenshots only as needed. -- Fall back to Playwright with Chromium only when Browser/IAB is unavailable, cannot access the page, cannot perform the interaction, or produces unreliable captures. State the fallback reason. Prefer harness-level browser tools or the Playwright CLI; do not assume a project-local Playwright package exists, and avoid fragile shell-quoted `node -e` verification scripts. -- If IAB screenshot capture stitches fixed headers incorrectly, times out, or cannot capture the needed viewport, continue Browser/IAB interaction checks but use Playwright Chromium for the screenshot comparison. -- Check at least one desktop viewport and one mobile-sized viewport when the UI is user-facing. -- For concept-first work, inspect the browser-rendered UI and use screenshots when helpful to compare it against the generated concept before finishing. Include the concept's native aspect/size when practical, plus desktop and mobile. Completion requires a side-by-side fidelity pass, not just build success, responsiveness, image loading, or interaction checks. -- Treat the first browser comparison as the start of the fidelity loop, not the finish line. Record the visible mismatches, fix them, and repeat browser verification until the page is correct. -- Verify exact preservation of concept content: headline, emphasized text, nav, CTAs, section order, proof points, brand mark, primary hero composition, next-section presence, color mood, and typography. -- For product UIs, dashboards, clones, games, and media surfaces, verify the surface-specific gates above in the browser-rendered UI. Do not substitute a generic "looks polished" judgment for a concept-structure check. -- Confirm generated assets load, are framed correctly, and do not obscure text or controls. -- Verify primary actions, navigation, hover/focus states, motion timing, interactive demos, responsive wrapping, and obvious loading or error states. -- Verify the core app workflow by clicking through it. Do not treat an interface as complete if the main controls are visually present but inert. -- If no browser verification path is available, state that as a blocker and do not claim the concept was implemented faithfully. -- In the final response, include the accepted concept path, Browser/IAB verification method or Playwright fallback reason, the material mismatches fixed, the core interaction path verified, and any remaining intentional deviations. If screenshots or reports were created only for QA, remove them before the final response unless the user explicitly asked to keep them or the benchmark contract requires them. +Run the app and verify the visible product, not just the build. + +1. Use Browser/IAB first. Load the app, inspect the first viewport, scroll, and click through the core workflow. +2. Check desktop, current browser viewport, and a mobile-sized viewport. +3. Capture or locate the accepted concept and the latest implementation screenshot. Use `view_image` on both in the same QA pass before final handoff; do not skip this step or substitute a browser glance for it. +4. Capture the implementation at the accepted concept's native dimensions when practical. If not practical, record the blocker and also verify the current browser viewport. +5. Write a fidelity ledger before final: mismatch, concept evidence, render evidence, and fix made or reason not fixed. Inspect at least five concrete comparison points covering copy, layout, typography, palette/gradients, asset treatment, spacing/container model, responsive behavior, or motion. +6. Compare side by side for copy, nav, CTA labels, section order, first-viewport balance, next-section visibility, palette, gradient treatment, font personality, type scale, spacing, borders, radii, container model, asset/background blending, motion, and simulated interactions. +7. Run an above-the-fold copy diff against the allowed copy list. Added, removed, renamed, or reordered visible copy must be fixed or listed as an intentional deviation; unapproved additions fail fidelity. +8. Audit typography everywhere, not just the hero or main canvas. Check headings, body, captions, labels, toolbar controls, sidebar rows, tabs, inputs, inspector fields, status bars, command palettes, export/share buttons, table cells, chart labels, and mobile line breaks. Use computed CSS sizes/weights/line-heights when the screenshot suggests drift. +9. For canvas/editor apps, audit app chrome separately from canvas/document text. Default zoom and pan are part of the spec; persisted local state must not hide seed, scale, or typography fixes during verification. +10. Ask explicitly: is this agency-signoff faithfully implemented, and would a great, highly skilled design agency sign off on this exact implementation of the accepted design? If anything would get a design-review comment, write a concrete repair checklist and keep editing. Do not final-answer with fixable visual issues. +11. Verify generated assets load, are framed correctly, and do not obscure text or controls. +12. Verify the core workflow updates real local UI state. Do not ship inert controls, fake media progress, hidden required media, or placeholder interactions. + +Functional QA does not count as fidelity QA. Passing build checks, clicking controls, or verifying local state cannot replace the concept-to-screenshot comparison, native-size check, and written mismatch ledger. + +Hard stops: clipped primary content, accidental wrapping, prototype-looking layout, rough seeded data, placeholder boxes, generic stock-like assets, unfinished cards, code-drawn game placeholders replacing concept art, invented visible copy, invented hero eyebrows/kickers/pills/badges, mismatched gradients, images that do not blend with the background, stale debug artifacts, unreadable text, type-scale drift, browser-default control typography, mobile overflow, unprofessional responsive collapse, or any visible drift from the accepted spec. + +## Surface Gates + +- Landing/company sites: preserve first viewport, hero role, brand/nav/CTA labels, section order, next-section preview, and signature imagery. +- Product/SaaS pages: preserve product mockups, workflow diagrams, feature strips, proof elements, and brand treatment. +- Dashboards/tools: preserve density, sidebars, headers, tables, tabs, timelines, charts, maps, row counts, and selected/detail behavior. Do not turn table-driven concepts into card grids. +- Canvas/editor tools: preserve default zoom/pan, canvas/document text scale, chrome density, toolbars, sidebars, inspector controls, layer rows, status bars, command surfaces, and autosaved/seed-state behavior. +- Timeline/planning tools: preserve grid/time-axis anatomy, row spans, event density, status rails, and command-center fit. +- Clone-like interfaces: preserve the recognizable skeleton before adding polish. Do not add marketing heroes or custom navigation that breaks the product type. +- Games: preserve the art direction with Image Gen assets for sprites, tiles/platforms, collectibles, hazards, goals/checkpoints, props, and background/parallax layers. Verify assets load, scale, animate or swap state correctly, align with collision geometry, and support movement, action/jump/drag behavior, scoring, hazards, and restart. +- Media surfaces: verify real media load, duration, play/pause, seek/progress, and visible frame changes. +- Forms/booking/purchase/restaurant flows: verify the main transaction path and confirmation state. + +## Final Response + +Include the accepted concept path, rendered screenshot method, Browser/IAB verification method or Playwright fallback reason, `view_image` inspection of the accepted concept and latest implementation screenshot, native-size viewport checked or blocker, at least five inspected comparison points, above-the-fold copy diff result, remaining intentional deviations, and an explicit statement that the implementation was faithfully verified against the accepted design. Also include material mismatches fixed and core interaction path verified. If no material mismatches remain, say so directly. diff --git a/skills/frontend-app-builder/references/imagegen-website-concepts.md b/skills/frontend-app-builder/references/imagegen-website-concepts.md index fc094a3..64ec00f 100644 --- a/skills/frontend-app-builder/references/imagegen-website-concepts.md +++ b/skills/frontend-app-builder/references/imagegen-website-concepts.md @@ -1,114 +1,93 @@ -# Imagegen Interface Concept Prompts +# Imagegen Interface Concept Briefing Guidance -Use this reference with the installed @imagegen skill when Frontend App Builder needs an overall visual concept before implementation. For new apps, dashboards, product interfaces, tools, games, websites, redesigns, and visually driven UI work from scratch, generate this concept unless the user explicitly says not to use Image Gen for concepting or asks you to follow existing code/design/art instead. +Use this reference with the installed @imagegen skill when Frontend App Builder needs an overall visual concept. This is guidance, not a prompt template. Write a natural design-director brief tailored to the task. -If the user asks to generate a concept ahead of time, review concept options, or wait for approval before implementation, stop after showing the generated concept and iterate with the user. Do not implement until the user approves the concept or asks to implement it. Once implementation starts, the approved concept becomes the active spec and must be implemented faithfully with browser verification. +## Must Include + +Copy concrete details from the user request, screenshots, existing app, or plan. Do not reduce them to a generic category like "modern landing page" or "clean dashboard." + +- Scope: complete page, complete app screen, multi-state product surface, dashboard, game screen, or coordinated section/state concepts. +- Purpose and audience: what the page/product helps the user do, and who it is for. +- Exact visible content: headlines, labels, CTAs, section names, nav items, table fields, sample entities, dates, prices, statuses, media requirements, and required copy. After a concept is accepted, this becomes the visible-copy lock. +- Structure: first viewport composition, downstream section order, sidebars, rails, drawers, grids, tables, charts, media areas, forms, footer/status regions, and responsive continuation. +- Interaction model: selected state, hover/focus affordances, filters, tabs, mode switches, creation/editing flow, success state, playback state, game HUD, or other local-state behavior the implementation must support. +- Visual system: palette mood, typography personality, content text scale, UI chrome/control text scale, density, spacing rhythm, radii, shadows, borders, container model, card usage, icon style, image treatment, brand mark direction, and reference style. +- Implementation constraints: code-native app UI text and controls, fully rendered product/background assets with their own text and branding when appropriate, separable assets, reusable component families, clear design-system tokens, accessible/responsive layout, and practical production design-spec handoff. +- Negative constraints: no header-only crops for full-surface work, no extra product areas, no fake metrics, no decorative filler, no default card grids, no hero eyebrow/kicker/pretitle/badge/pill above the main heading unless explicitly requested or present in the reference, no gradients that conflict with the design direction, no pasted-in images that fail to blend with the background, no unrelated sections, no new claims, and no moving true app UI text into images. ## Quality Bar -Every interface concept should optimize for high-taste restraint: +Every concept should feel like a professional product mockup by a senior product designer: -- Agency-quality, minimal, polished, and intentional. -- One clear focal idea per viewport. -- Generous whitespace and strong hierarchy. -- Restrained color system with one or two purposeful accents. -- Elegant, readable typography with tasteful contrast. -- Fewer components, better executed. -- Clean UI with restrained content density by default. -- No extra content, sections, cards, metrics, labels, or decorative UI unless they directly support the user's request. -- Landing pages should make the offer, product signal, and primary action obvious without cramming the first viewport. -- Product interfaces and dashboards should feel useful and believable, with clear workflows, readable states, intentional density, and controls that can become clickable local-state interactions in the implementation. -- The concept must be implementable as a product surface, not just attractive art: show the primary workflow anatomy, real media/product area when relevant, and enough layout detail for faithful code translation. -- Game interfaces should establish the play surface, HUD/control placement, visual mood, and interaction affordances without cluttering the player's focus. +- Clean, airy, distinctive, and not repetitive by default. +- One clear creative idea or visual point of view. +- Full requested surface, not just a hero, unless the user only asked for a hero. +- Strong first viewport with clear offer, product signal, and primary action. +- Coherent full-page rhythm across sections, states, and responsive continuation, without repetitive card stacks or repeated section formulas. +- Excellent typography and intentional whitespace, including buttons, tabs, inputs, sidebars, table cells, labels, and other control chrome. +- Consistent visual system: palette, gradients, spacing, components, icon style, imagery, shadows, borders, and container model. +- Clear design-system signal: typography scale, control text styles, reusable component families, variants, spacing rhythm, and tokens that can be extracted before coding. +- High-quality assets for logos, brand marks, hero imagery, product renders, background scenes, illustrations, textures, thumbnails, posters, avatars, or empty states. Product/background assets should be fully rendered with consistent branding and in-image text when that text belongs to the asset. +- Purposeful motion/interaction cues that can be implemented later. +- Specific, non-generic copy when the user has not supplied exact copy. -Avoid over-designed output unless the user explicitly asks for it: +Default to roughly 7/10 creativity: distinctive and art-directed, but still implementable. "Clean" means airy, edited, legible, not cluttered, and not repetitive. -- Busy sci-fi dashboards, cyberpunk HUD overlays, neon grids, excessive glow, and floating metric panels. -- Crammed feature-card walls, unnecessary badges, redundant icon rows, fake charts, and fake metrics. -- Decorative elements that do not clarify the product, action, or story. -- Generic stock-style layouts, placeholder gray boxes, unreadable UI text, fake brand names, and watermarks. -- Filling whitespace with content just because the canvas has room. -- Dense first screens unless the user specifically requested an operational dashboard, data-heavy interface, or game HUD that genuinely needs that density. +Avoid: unnecessary cards, hero eyebrow/kicker labels, pills, badges, stats, icon rows, fake charts, fake metrics, fake jargon, generic brand names, bokeh/orb decoration, neon grids, excessive glow, mismatched gradients, pasted-looking images, unreadable text, and filling whitespace just because it exists. -## Full Page Or App Concept +## Surface Guidance -Use for new creative websites, landing pages, product pages, portfolios, microsites, dashboards, app screens, tools, game UIs, and visually distinctive app surfaces. +Full page or app: -```text -Use case: ui-mockup -Asset type: full-page or app interface concept for implementation reference -Primary request: -Page purpose: -Audience: -Content priorities: -Style/medium: high-taste agency-quality web UI mockup, minimal polished production-ready interface -Composition/framing: ; one clear focal idea, generous whitespace, restrained section count, no visual crowding -Typography direction: elegant readable web typography; -Color palette: ; restrained with one or two purposeful accents -Imagery: -Interaction feel: -Motion/interaction direction: -Constraints: keep UI clean, intentional, and uncluttered; embrace whitespace; use less content unless the user explicitly asks for more or the dashboard/game requires intentional density; fewer elements, better hierarchy; include enough visual language to extend the rest of the page if the concept only shows one viewport; make app controls and workflow states implementable with local state; avoid unnecessary badges, cards, charts, icons, stats, HUD elements, controls, or decorative sections; keep exact copy and controls for code implementation -Avoid: busy dashboards, cyberpunk HUD overlays, neon grids, excessive glow, floating metric panels, crammed feature grids, overbuilt game HUDs, placeholder gray boxes, unreadable dense text, fake brand names, watermarks -``` +- Ask for enough structure to implement the whole requested surface: first viewport, section rhythm, product/workflow anatomy, downstream sections or states, and responsive continuation. +- Marketing/product pages need a strong hero and clear CTA before proof or feature density. Do not put an eyebrow, kicker, pretitle, badge, or pill above the hero heading unless the user asked for it or the reference already uses it. Use interactive hero UI only for SaaS/software previews, product demos, or purposeful interactive animation; otherwise prefer faithful branded product/background imagery. +- App screens, dashboards, and tools need the real interaction model: sidebars, panels, tables, timelines, charts, controls, modes, selected states, and primary workflow. +- Games need the play surface, HUD/control placement, art direction, reward/hazard language, interaction affordances, and a follow-on production asset pass for sprites, tiles/platforms, collectibles, hazards, goals, props, and background/parallax layers. -## Redesign From Screenshot +Redesign from screenshot: -Use when an existing site or app should be refreshed, restyled, modernized, or adapted to a new visual style. +- Use the screenshot as the edit target when preserving information architecture matters. +- Preserve navigation meaning, product/brand cues, content hierarchy, controls, and page purpose. +- Improve spacing, typography, visual hierarchy, color, image treatment, and component polish without inventing unrelated sections, fake metrics, new claims, or new product areas. -```text -Use case: style-transfer -Asset type: website redesign concept for implementation reference -Input images: Image 1: edit target or visual reference screenshot of the existing website -Primary request: redesign the existing page with -Preserve: information architecture, core content hierarchy, navigation meaning, product/brand cues, and page purpose -Improve: visual hierarchy, spacing, typography, color, imagery, component polish, and overall composition through simplification, restraint, and better whitespace -Typography direction: -Color palette: ; calmer, fewer accents -Motion/interaction direction: -Constraints: change the visual treatment only; make it more minimal, premium, whitespace-forward, and agency-quality; reduce clutter rather than adding content; preserve the real workflow and controls so the implementation can be interactive; do not invent unrelated sections, fake metrics, fake logos, or new product claims; keep exact production copy for code implementation -Avoid: clutter, excessive decoration, cyberpunk HUD elements, neon grid overlays, floating metric cards, unreadable text, watermarks -``` +Hero or section: -If the screenshot is only a loose reference, label it as a reference image rather than an edit target and generate a new `ui-mockup` concept. +- Only use this path when the user asks for a section, hero, pricing block, feature section, or other page slice. +- Include surrounding context and enough visual language to continue the page consistently. -## Hero Or Section Concept +Content-heavy pages: -Use when the user asks mainly for a beautiful hero, above-the-fold treatment, pricing section, feature section, or other visually defined page slice. +- For multi-section websites and long landing pages, default to coordinated section concepts: one image per major section, with an optional overview only for full-page rhythm. +- Avoid one huge full-page screenshot when it would reduce section detail, weaken hierarchy, or make implementation matching harder. +- Keep one accepted layout concept responsible for overall structure and section order. +- All supporting concepts must share brand language, typography, palette, component geometry, asset style, spacing, and density. -```text -Use case: ui-mockup -Asset type: website section concept for implementation reference -Primary request: -Section role: -Surrounding page context: -Composition/framing: -Typography direction: -Imagery/materials: -Motion/interaction direction: -Constraints: design the section as implementable HTML/CSS UI; use one strong focal point; embrace whitespace; keep controls, labels, and final text in code; avoid unnecessary UI elements or excess content -Avoid: generic gradients, decorative filler, excessive cards, floating panels, unreadable UI text, watermarks -``` +## Asset Planning + +- Keep real app UI text, form fields, nav, metrics, and controls in code. +- Product images, background assets, posters, packaging, signage, hero photos, and brand scenes should be rendered completely by Image Gen with the text, logos, marks, labels, and branding that belong in the asset. Quote exact asset text and require verbatim rendering when text matters. +- If the concept includes a logo, brand mark, product label, package, poster, sign, product render, or branded background object, use Image Gen editing to create standalone matching assets before coding so the implementation keeps coherent branding. +- Request transparent backgrounds or clean cutouts when assets need to layer into code-native UI. +- For games, generate transparent character/state sprites or sprite sheets, terrain/platform tiles, collectibles, hazards, goal/checkpoint objects, props, and 2-3 parallax/background layers when the concept calls for depth. Keep HUD text, score, controls, collision boxes, physics, and game state code-native. +- Use generated assets for logos, brand marks, hero imagery, product renders, editorial imagery, background scenes, cutouts, textures, posters, thumbnails, avatars, empty-state art, and illustrated objects. +- Do not crop a full-page concept into production UI as a shortcut. Recreate or isolate needed assets with Image Gen. +- SVG is fine for faithful icons. Use Image Gen for logos, brand marks, and non-icon visual assets. +- Supporting asset concepts must match the accepted layout concept; they must not introduce a new visual direction. ## After Generation -- Inspect the concept before coding. Extract the exact content, information architecture, and design system choices instead of treating the generated image as loose inspiration. -- Reject busy concepts before implementation. If it looks crammed, ask imagegen for a calmer version with fewer elements, more whitespace, a stronger focal point, and a more restrained palette. -- List the concrete implementation decisions: exact copy, nav items, CTA labels, section order, brand mark treatment, hero composition, layout, color tokens, type scale, spacing, radius, borders, shadows, image treatment, motion behavior, interactivity, core workflow, and responsive changes. -- Capture a concept-to-implementation inventory before coding: native concept size/aspect, first-viewport composition, headline line breaks, nav/header geometry, brand mark, panel/card topology, row counts, chart axes, drawers/rails, footer/status regions, data/copy values, asset roles, and visible control states. -- Treat the accepted concept as the visual specification for implementation. The coded result should match the concept's composition, hierarchy, proportions, palette, typography direction, and asset treatment as closely as possible. -- If the concept does not show the full requested page, extend the rest of the implementation in the same design language: spacing, type scale, palette, component geometry, imagery style, density, and interaction model. -- Generate individual raster assets after the overall concept is accepted when they are needed for fidelity: logos, brand marks, hero imagery, product mockups, editorial imagery, cutouts, textures, posters, thumbnails, avatars, or illustrations that are visible in the concept. -- Additional image generation should reproduce or isolate assets from the accepted concept. Do not create a second hero, character, product mockup, dashboard, or visual motif that changes the design direction. -- Do not use SVGs as stand-ins for generated visual assets. Use SVG only for icons, and recreate those icons faithfully or use an existing icon system only when it matches the concept accurately. Use imagegen for logos and brand marks unless the user provided an existing vector asset. -- Bring concept elements to life when they imply product behavior. Dashboards, charts, cards, maps, timelines, device frames, canvases, product mockups, or process flows should get believable hover states, animated state changes, lightweight controls, or simulated interactive demos when feasible. -- For app interfaces, implement the main user journey so the user can click through the product idea with believable local state, not just inspect a static composition. Controls shown in the concept should work against real local UI state. -- For media concepts, ensure posters and generated imagery do not hide required real video/audio playback. The implementation must verify the real media loads, plays, seeks, and changes visible frames. -- For clone-like UI concepts, preserve the recognizable skeleton and designed mock state before adding polish or live data. -- Keep final UI text, form fields, navigation, and interactive controls in code. -- Move only project-consumed final assets into the workspace. Preview concepts can stay in imagegen's default generated image location unless the user asks to keep them. -- Verify the implemented page in the Browser plugin / built-in app browser first. Load the app, inspect the first viewport, scroll, and click through the core workflow before falling back to Playwright. -- Use Playwright with Chromium only when Browser/IAB is unavailable, cannot access the page, cannot perform the needed interaction, or produces unreliable captures. State the fallback reason. -- Verify the implemented page against the concept before finishing. Compare the running UI, using transient screenshots when helpful, for layout, spacing, typography, color, image crops, motion, interactivity, and overall polish, then iterate on the code or assets until the result would pass a professional design-agency inspection. Keep going through this loop; do not stop at a partial implementation, a build that merely compiles, or a page that only captures the general vibe. -- Perform an agency pass before final: compare the concept-native aspect when practical, desktop, and mobile; name at least five concrete mismatches and fix them, or explicitly state that no material mismatches remain. Structural mismatches in topology, branding, copy, density, media behavior, or primary workflow block completion. -- Remove temporary QA-only screenshots, reports, scratch notes, and intermediate generated assets before handoff unless the user or benchmark explicitly requires them. The accepted concept image may remain available for user iteration. +- Reject concepts that are header-only for full-surface asks, cluttered, generic, repetitive, under-specified, unreadable, over-decorated, or impractical to implement. +- Extract a design system before coding: native aspect, layout, section order, copy, nav, CTAs, palette, spacing scale, content typography, UI chrome typography, reusable component families, variants, container model, assets, state, and responsive continuation. +- Treat the accepted concept as the visual spec. Match composition, hierarchy, palette, gradients, typography, spacing, imagery, components, container model, and asset treatment. Do not strip text or branding out of generated product/background assets just because app UI text should stay code-native. +- For multi-section pages, implement and verify one section or contiguous viewport at a time. Compare the browser screenshot to that section's concept, fix visible drift, then move to the next section. +- Build an allowed above-the-fold copy list from the accepted concept and user-provided copy. Do not add new hero, nav, eyebrow/kicker, CTA, label, subtitle, category, or proof text unless it is recorded as an intentional deviation. Semantic H1 or heading-level changes must not invent visible explanatory copy. +- Do not add decorative hero eyebrows, pills, badges, gradients, or overlays that were not in the accepted design. Images must blend with the surrounding background through matching color, lighting, crop, transparency, edges, and shadow. +- Do not add UI that does not exist in the design. Generate missing section/state concepts when visual consistency is uncertain. +- For games, do not replace the accepted art direction with code-drawn placeholder shapes for characters, terrain, collectibles, hazards, goals, or backgrounds. Use Image Gen assets unless a concrete blocker or approved deviation is recorded. +- Preserve the accepted container model. Do not add cards, floating panels, bordered tiles, or card grids where the spec uses open layout, bands, lists, tables, rails, canvases, or full-bleed composition. +- Use Browser/IAB first for verification; use Playwright Chromium only when Browser/IAB is unavailable or unreliable. +- Before final handoff, use `view_image` on the accepted concept and latest browser screenshot in the same QA pass. This cannot be skipped or replaced with browser inspection or functional testing alone. +- Capture the implementation at the accepted concept's native dimensions when practical; otherwise record the blocker and also verify the current browser viewport. +- Write a fidelity ledger before final: mismatch, concept evidence, render evidence, and fix made or reason not fixed. Inspect at least five concrete comparison points before claiming fidelity. +- Judge whether the implementation is agency-signoff faithful and whether a great, highly skilled design agency would sign off on it; include type-scale drift and default-looking control text in that judgment. If not, keep iterating until it would sign off or a concrete blocker remains. +- Remove temporary QA screenshots, reports, scratch notes, and unused generated assets unless the task requires keeping them. diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index ba14cfe..ef4c231 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: hyperframes-cli -description: HyperFrames CLI tool — hyperframes init, lint, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting or validating compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment. +description: HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment. --- # HyperFrames CLI @@ -12,10 +12,11 @@ Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg. 1. **Scaffold** — `npx hyperframes init my-video` 2. **Write** — author HTML composition (see the `hyperframes` skill) 3. **Lint** — `npx hyperframes lint` -4. **Preview** — `npx hyperframes preview` -5. **Render** — `npx hyperframes render` +4. **Visual inspect** — `npx hyperframes inspect` +5. **Preview** — `npx hyperframes preview` +6. **Render** — `npx hyperframes render` -Lint before preview — catches missing `data-composition-id`, overlapping tracks, unregistered timelines. +Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas. ## Scaffolding @@ -42,6 +43,27 @@ npx hyperframes lint --json # machine-readable Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). +## Visual Inspect + +```bash +npx hyperframes inspect # inspect rendered layout over the timeline +npx hyperframes inspect ./my-project # specific project +npx hyperframes inspect --json # agent-readable findings +npx hyperframes inspect --samples 15 # denser timeline sweep +npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps +``` + +Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports: + +- Text extending outside the nearest visual container or bubble +- Text clipped by its own fixed-width/fixed-height box +- Text extending outside the composition canvas +- Children escaping clipping containers + +Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`. + +`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass. + ## Previewing ```bash @@ -51,6 +73,20 @@ npx hyperframes preview --port 4567 # custom port (default 3002) Hot-reloads on file changes. Opens the studio in your browser automatically. +When handing a project back to the user, use the Studio project URL, not the +source `index.html` path: + +```text +http://localhost:/#project/ +``` + +Use the actual port from the preview output and the project directory name. For +example, after `npx hyperframes preview --port 3017` in `codex-openai-video`, +report `http://localhost:3017/#project/codex-openai-video`. + +Treat `index.html` as source-code context only. It is fine to link it as an +implementation file, but do not label it as the project or preview surface. + ## Rendering ```bash diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 5584493..60f816e 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -277,11 +277,28 @@ When no `visual-style.md` or animation direction is provided, follow [house-styl ## Output Checklist - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass +- [ ] `npx hyperframes inspect` passes, or every reported overflow is intentionally marked - [ ] Contrast warnings addressed (see Quality Checks below) +- [ ] Layout issues addressed (see Quality Checks below) - [ ] Animation choreography verified (see Quality Checks below) ## Quality Checks +### Visual Inspect + +`hyperframes inspect` runs the composition in headless Chrome, seeks through the timeline, and maps visual layout issues with timestamps, selectors, bounding boxes, and fix hints. Run it after `lint` and `validate`: + +```bash +npx hyperframes inspect +npx hyperframes inspect --json +``` + +Failures usually mean text is spilling out of a bubble/card, a fixed-size label is clipping dynamic copy, or text has moved off the canvas. Fix by increasing container size or padding, reducing font size or letter spacing, adding a real `max-width` so text wraps inside the container, or using `window.__hyperframes.fitTextFontSize(...)` for dynamic copy. + +Use `--samples 15` for dense videos and `--at 1.5,4,7.25` for specific hero frames. Repeated static issues are collapsed by default to avoid flooding agent context. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`. + +`hyperframes layout` is the compatibility alias for the same check. + ### Contrast `hyperframes validate` runs a WCAG contrast audit by default. It seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and computes contrast ratios. Failures appear as warnings: diff --git a/skills/mcp-tool-hint-justifications/agents/openai.yaml b/skills/mcp-tool-hint-justifications/agents/openai.yaml new file mode 100644 index 0000000..4f9ede4 --- /dev/null +++ b/skills/mcp-tool-hint-justifications/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: "MCP Tool Hint Justifications" + short_description: "Generate Apps SDK tool hint justification files" diff --git a/skills/website-to-hyperframes/SKILL.md b/skills/website-to-hyperframes/SKILL.md index 8a96b5b..2233ffd 100644 --- a/skills/website-to-hyperframes/SKILL.md +++ b/skills/website-to-hyperframes/SKILL.md @@ -83,9 +83,12 @@ Build each composition following the storyboard. After each one: self-review for **Read:** [references/step-7-validate.md](references/step-7-validate.md) -Lint, validate, snapshot, preview. Deliver the preview to the user first — only render to MP4 on explicit request. +Lint, validate, snapshot, preview. Deliver the localhost Studio project URL +(`http://localhost:/#project/`) to the user first — only +render to MP4 on explicit request. Do not treat `index.html` as the project +handoff link; it is source-code context only. -**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors. +**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors, and the final response includes the active Studio project URL. --- diff --git a/skills/website-to-hyperframes/references/step-6-build.md b/skills/website-to-hyperframes/references/step-6-build.md index c04c599..0021cca 100644 --- a/skills/website-to-hyperframes/references/step-6-build.md +++ b/skills/website-to-hyperframes/references/step-6-build.md @@ -114,7 +114,7 @@ After building the composition, check WITH ACTUAL CODE: - [ ] No full-screen dark linear gradients (H.264 creates visible banding — use solid + localized radial glows) - [ ] Timeline registered: `window.__timelines["comp-id"] = tl` - [ ] Colors match DESIGN.md exactly (paste the HEX value, don't approximate) -- [ ] **Every `