DESIGN.md UI Designer#

Use this skill to turn a UI task into a durable design system plus verified screens. It is especially useful for CWS public pages, extension UIs, landing pages, dashboards, apps, communities, courses, video ideation boards, and product pages where visual quality and repeatable iteration matter.

For any new product, extension, app, skill, course, template, or community that needs a public surface, design the Cloudflare Pages landing system as part of the product, not as an afterthought. The public surface must include a high-end landing page plus privacy, support, reviewer or verification, and source or transparency pages when applicable. Do not ship several products with the same thumbnail, hero, screenshot framing, icon motif, or visual signature.

Core Workflow#

1. Read the current UI first: source files, live URL when relevant, screenshots, brand/product context, and existing assets.
2. Create or update a repo-local DESIGN.md before broad visual edits when the product does not already have one.
3. Keep DESIGN.md compact and agent-usable: YAML tokens for exact values, markdown rationale for how to apply them.
4. Implement UI changes using the design tokens and existing framework patterns.
5. Verify with real rendered screenshots at mobile, tablet, and desktop widths.
6. Run accessibility and layout checks: image loading, focus states, contrast, no horizontal overflow, no text clipping, no incoherent overlap.
7. For public/reviewer pages, verify claims are true, links work, and the first viewport clearly signals the product.
8. Verify Cloudflare Pages SEO and deployment readiness: canonical HTTPS Pages URLs, title and meta description, social preview image, sitemap, robots.txt, security headers, and SoftwareApplication JSON-LD for apps and extensions.
9. For marketing landings, run the conversion landing workflow before visual polish: first traffic source, one reader, trust reason, share moment, offer, proof receipts, SEO article cluster, and honest monetization boundary.
10. Run the critic score gate. Do not ship low-trust public pages, CWS media, or extension UI that fails the score threshold.

DESIGN.md Contract#

Prefer this structure:

markdown

---
version: "alpha"
name: Product Design System
description: One sentence about the product surface.
colors:
  primary: "#111827"
  accent: "#1D4ED8"
typography:
  h1:
    fontFamily: Inter
    fontSize: 3rem
    fontWeight: 780
    lineHeight: 1.04
    letterSpacing: 0
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.md}"
---

## Overview
## Colors
## Typography
## Layout
## Elevation
## Shapes
## Components
## Do's and Don'ts

Rules:

• Tokens are normative; prose explains intent and usage.
• Keep font sizes stable across viewports; do not scale text with viewport width.
• Use 0 letter spacing unless the product has an explicit typography reason.
• Use cards only for repeated items, modals, and framed tools.
• Avoid nested cards, decorative blobs, generic gradients, and purely atmospheric assets.
• Use product-relevant images or real screenshots where users need to inspect the product.
• For CWS listing screenshots, use actual extension UI with sanitized fixture data, never generated product mocks.
• Each product must have a distinct design identity: icon motif, hero art, screenshot framing, promo layout, palette role, and visual signature.

Cloudflare Pages Product Landing Contract#

For every public product surface, create or maintain:

• homepage landing page with a first-viewport product signal, concrete workflow evidence, real screenshots or rendered app state, clear free MVP or install path, and no exaggerated outcome claims;
• privacy page that matches implementation and permissions exactly;
• support page with product-specific issue paths and contact/diagnostic detail;
• reviewer, verification, or test page with reproducible smoke-test steps when the product is reviewable, installable, or submitted to a marketplace;
• source, transparency, or release page when a source archive, policy packet, or reviewer artifact is part of the trust story;
• SEO baseline: title, description, canonical, social preview card, sitemap, robots, security headers, and structured data where relevant.

Use Cloudflare Pages URLs as canonical public URLs for marketplace submissions. Do not leave GitHub Pages, localhost, preview URLs, or stale dashboard URLs as canonical after a Cloudflare Pages deployment exists.

High-end landing pages must feel like a specific product solving a specific problem. Avoid SaaS-template filler, generic AI-gradient heroes, duplicated thumbnail systems, fake UI mockups, and vague "boost productivity" copy. The first viewport should show either the product itself, the artifact it creates, or the real workflow state users came for.

Marketing Landing Conversion Workflow#

Use this workflow for paid or monetizable product landings, Chrome extension public pages, skill-pack pages, launch pages, and SEO hubs. Load references/marketing-landing.md when the task involves offer positioning, trust building, article thumbnails, pricing, or a conversion critique.

Before designing the page, write a compact launch brief:

• first traffic source: exact post, search query, marketplace listing, newsletter, community, partner, or profile that will send qualified visitors;
• one reader: the concrete operator who arrives and what painful moment made them search, click, or share;
• share moment: the exact page artifact, result, article, checklist, or before/after insight the visitor would send to someone else;
• trust reason: why a skeptical buyer should believe the claim now, using real screenshots, dataset scope, source archive, reviewer guide, named public evidence, or transparent boundaries;
• free MVP path and paid path: what is free today, what may be monetized, how updates are delivered, and what is deliberately not promised.

The page structure should be evidence-first, not template-first:

• hero: literal product or offer name, one specific use case, visible product state or artifact, one CTA, and no unverifiable outcome promise;
• proof strip: permissions, privacy, source/date, dataset size, version, reviewer path, or benchmark facts instead of vague badges;
• included/workflow section: what the buyer receives or can do, with stable update policy and deliverable boundaries;
• persona/use-case section: 3-4 concrete readers and the situation where the product is worth sharing;
• trust receipts: real artifacts, public screenshots, source links, test gates, reviewer instructions, or release notes. Do not invent testimonials, logos, revenue numbers, review speed, or buyer identities;
• content hub: 3-9 SEO articles or playbooks when education is needed. Give each article a video-style thumbnail, search-intent title, internal links, and a concrete operator task;
• pricing/FAQ/final CTA: answer refund, delivery, compatibility, updates, privacy, affiliation, and support questions without hiding risk.

Third-party brand usage must stay honest. Blog/editorial thumbnails may use a third-party product/community name as a topic cue when the article is actually about that ecosystem and the user has asked for it. Do not use official logos, brand marks, or endorsement-like placement in landing heroes, CWS assets, product proof, or marketplace media unless rights are explicit. Keep a visible non-affiliation boundary on relevant pages.

Image Generation#

When generated raster imagery is needed, use the imagegen skill/tool. The required designer preference is gpt-image-2-2026-04-21 when the host exposes model selection. If model selection is not exposed, use the available image tool and record that limitation.

For UI/UX redesigns, run a holistic screen-look exploration before committing to large visual edits:

1. Capture the current UI exactly as users see it in the browser at desktop and mobile widths. Include the full first viewport and the primary working surface; for extensions, capture popup, options, store, and support pages when relevant.
2. Summarize the visible product truth from those screenshots: what the user can do, what evidence is visible, what feels crowded or generic, and where trust is lost.
3. Feed the screenshot context and summary into gpt-image-2-2026-04-21 for full-screen design look candidates when model selection is available. Ask for complete viewport compositions, not isolated components or decorative hero art.
4. Generate or describe 2-3 candidate directions, then choose the strongest one against the critic score gate before editing code.
5. Build from the selected candidate using repo-native components, real product screenshots/assets, and DESIGN.md tokens. Treat generated UI looks as direction, not factual product evidence.
6. Re-capture the same viewports after implementation and compare against the original screen: hierarchy, density, interaction clarity, overflow, and trust.

Use a concrete art direction before generation:

• product truth: what real product state or workflow the image supports
• composition: target size, focal object, negative space, crop safety, thumbnail legibility, and where text will sit if text is overlaid in HTML/CSS
• visual identity: palette, material, lighting, icon/object language, and how it follows DESIGN.md
• exclusions: no generic blobs, fake UI screenshots, unreadable pseudo-text, unrelated metaphors, or atmospheric stock-style filler

Use generated imagery for:

• landing-page hero art
• promo tiles
• empty-state art
• design exploration
• background product context
• distinct marketplace thumbnails when they are not used as product evidence

Do not use generated imagery as fake product UI evidence, policy proof, or CWS screenshots.

For CWS promo tiles and public review pages, prefer generated bitmap art only when it improves trust and still points back to the real product. Pair promo art with real screenshots where reviewers need to inspect functionality.

Community And Video Media Workflow#

Use this stricter workflow for Skool/community covers, course thumbnails, post cards, proof cards, short-form video concepts, Manim scenes, and video ideation boards. These assets are public traffic surfaces, not decorative extras.

1. Name the first traffic source before designing: exact community, profile, search query, post format, or partner loop where the first qualified viewers will come from.
2. Name the share moment: the exact point where the viewer would send the asset to a friend, tag someone, save it, or repost it.
3. Build the asset around real product truth: the real community activity, template, proof artifact, lesson, app state, or creator-owned example.
4. Draft at least 7 video or media candidates before selecting one. Each candidate needs hook, audience, proof artifact, incentive, CTA, privacy boundary, share trigger, and kill/iterate decision.
5. Use generated imagery only when it adds a concrete, ownable visual system. Do not use generic AI gradients, fake dashboards, stock course covers, unreadable pseudo-text, or reused sibling-product thumbnails.
6. For Manim or motion assets, validate aspect ratio, duration, fps, thumbnail, first-frame clarity, captions/metadata, and source ownership before treating the file as publishable.
7. Mark weak drafts as prototype_only or rework; do not present them as launch-ready media.

High-end community/video media must score at least 90/100 overall and no category can be below 9/10:

• traffic fit
• share trigger
• product truth
• visual distinction
• thumbnail and crop readability
• motion or composition quality
• privacy and rights safety
• incentive clarity
• conversion path quality

Block finalization when the score is below threshold. A working render, prompt, or thumbnail is not enough. Iterate or kill the candidate.

For marketing landings and SEO hubs, also score the launch brief and content system. Block finalization if the combined landing score is below 90/100 or if traffic source, share moment, proof integrity, pricing boundary, or article cluster quality scores below 9/10.

Critic Score Gate#

Score every changed public page, extension popup, CWS screenshot, promo tile, hero, and media asset before final delivery. Use a 0-10 score for each category and record the scores in the task summary or repo log for release work.

Block finalization if any category is below 8/10:

• product clarity: the first viewport or asset immediately tells what the product is and what the user can do
• visual trust: typography, spacing, palette, imagery, and hierarchy feel intentional and credible rather than default, low-effort, or generic
• evidence integrity: screenshots show real UI with sanitized data; generated images are not misrepresented as product evidence
• responsive polish: mobile, tablet, and desktop have no clipping, overlap, awkward crop, tiny unreadable text, or horizontal overflow
• accessibility: contrast, focus states, readable type sizes, controls, and tappable targets meet practical review expectations
• claim alignment: visible text and media only describe shipped, reproducible behavior
• conversion path quality: first action is specific, honest, free or reviewable when the MVP is rough, and tied to the product's share or proof moment
• uniqueness: the visual system is materially distinct from sibling products and current marketplace competitors

When the score is below threshold, iterate visually before shipping. Improve the design system, regenerate or replace weak assets, refine layout density, and run screenshots again. Do not excuse weak visuals as "only policy pages"; CWS reviewer pages and store assets must build product trust.

Verification Gate#

Before finalizing UI work, capture or inspect rendered screenshots for:

• 320px or 360px mobile
• 390px mobile
• 768px tablet
• 1280px or wider desktop

Check:

• no broken images
• no horizontal overflow
• no text clipped inside buttons/cards/nav
• keyboard focus is visible
• tap targets are comfortable
• first viewport has the required brand/product signal
• claims match real product behavior
• critic score gate is recorded and all categories are at least 8/10
• all Cloudflare Pages canonical URLs, policy URLs, support URLs, and reviewer URLs resolve to the correct product
• public pages pass SEO and security-header checks when the repo provides them
• product thumbnails, promo images, and hero assets are unique across sibling products

For Chrome extensions, combine this skill with chrome-extension-cws-shipper. For submitted or pending-review marketplace items, do not alter the submitted package or CWS dashboard draft just to improve design; prepare the improved Cloudflare Pages surface and carry design changes into the next submitted version unless the marketplace reports a blocker.

Source Notes#

Use references/source-notes.md for the source-derived principles behind this workflow and links to the design.md, DESIGN.md directory, and Codex use-case references.