# Web Design Studio

> Production-grade standalone websites with distinctive art direction, Codex-generated raster imagery, and a verified delivery workflow.

Web Design Studio is a Codex skill for creating or redesigning static websites in semantic HTML, CSS, and JavaScript. It is intentionally scoped to landing pages, marketing sites, portfolios, product pages, editorial sites, and static dashboards that do not require an application framework.

## Highlights

- **Focused static-site scope** — works with standalone HTML, CSS, and JavaScript while preserving existing static project structures.
- **Distinctive art direction** — establishes a deliberate visual concept, design system, responsive composition, and restrained motion language before implementation.
- **Codex-native image generation** — creates every new raster asset with the built-in `image_gen` tool through the `imagegen` skill.
- **Finished, factual content** — rejects Lorem Ipsum, placeholder media, unsupported product claims, and generic filler sections.
- **Accessible implementation** — requires semantic landmarks, keyboard support, visible focus, useful alternative text, sufficient contrast, and reduced-motion support.
- **Performance-aware assets** — requires dimensions or aspect ratios, hero-image priority, responsive crops, and lazy loading below the fold.
- **Recursive asset verification** — validates HTML and CSS references including `src`, `srcset`, `<source>`, video posters, social images, icons, and CSS `url()`.
- **Optional Chinese handoff** — generates a Simplified Chinese design handoff only when the user explicitly requests one.

## Scope

Use this skill for standalone static websites. Route React, Vue, Next.js, Svelte, and other framework-based projects to an appropriate framework or frontend skill. Deployment and hosting are also outside this skill unless separately requested.

For a new empty project, the default structure is:

```text
index.html
styles.css
script.js
images/
```

Existing static sites keep their current structure and conventions.

## Workflow

1. Audit the project, instructions, content, interactions, and existing assets.
2. Define the page purpose, audience, information hierarchy, and conversion points.
3. Commit to one art direction and a compact design system.
4. Plan every raster asset with placement-aware briefs.
5. Generate each new raster asset with Codex and inspect the result.
6. Implement the complete responsive and accessible static site.
7. Verify local assets and inspect representative browser widths.
8. Generate a Simplified Chinese handoff only when explicitly requested.
9. Deliver the entry page, asset paths, verification results, and requested documentation.

## Image generation

New hero art, product imagery, editorial photography, illustrations, and textures are generated with Codex's built-in image generation. The skill does not use stock-image search, external generation services, separate credentials, or a project-local image generation script.

User-provided logos, brand assets, photographs, and reference images are preserved. Precise UI icons, vector marks, diagrams, and structural geometry remain native HTML, CSS, or SVG.

Each generated asset receives its own prompt covering:

- use case and page placement
- aspect ratio, crop, safe areas, and negative space
- subject, environment, medium, lighting, and palette
- required invariants and prohibited elements
- exact in-image text only when necessary

Selected outputs are copied into the project's asset directory with descriptive kebab-case names. Existing files are not overwritten unless the user explicitly requests it.

## Utilities

### Verify local visual assets

```bash
python3 skills/web-design-studio/scripts/verify_images.py \
  --html-dir path/to/site \
  --images-dir images
```

The verifier recursively scans HTML and CSS, resolves relative and root-relative paths, and skips external, data, blob, and anchor references.

Exit codes:

- `0` — every local reference resolves
- `1` — one or more local assets are missing
- `2` — invalid arguments or unreadable source files

### Generate a Simplified Chinese handoff

Run this only when the user explicitly requests a design specification or client handoff:

```bash
python3 skills/web-design-studio/scripts/generate_design_doc.py \
  --project-name "Project Name" \
  --output "design-doc-project.html" \
  --html-file "path/to/site/index.html"
```

The generator can discover local stylesheets, CSS variables, page sections, images, real pixel dimensions, and Chinese or English calls to action. Manual inputs such as `--design-goals`, `--features`, and `--css-file` override or enrich extracted content. User-supplied and page-extracted values are HTML-escaped.

## Installation

### skills.sh

```bash
npx skills add xiaodong-wu/web-design-studio
```

### Manual

Copy `skills/web-design-studio` into a Codex-compatible skills directory, then restart or reload the client.

## Usage

Invoke the skill explicitly:

```text
Use $web-design-studio to create a distinctive static landing page for a specialty coffee roaster.
```

To request the optional handoff:

```text
Use $web-design-studio to redesign this static site and include a Simplified Chinese client handoff document.
```

## Repository structure

```text
web-design-studio/
├── README.md
├── CHANGELOG.md
├── LICENSE.txt
└── skills/
    └── web-design-studio/
        ├── SKILL.md
        ├── LICENSE.txt
        ├── agents/
        │   └── openai.yaml
        └── scripts/
            ├── generate_design_doc.py
            └── verify_images.py
```

## Requirements

- A Codex environment with the built-in `imagegen` skill and `image_gen` tool for new raster assets
- Python 3.10 or newer for the bundled verification and handoff scripts
- A browser-control capability for visual QA when available

The bundled Python scripts use only the standard library.

## License

Apache 2.0. See [LICENSE.txt](LICENSE.txt).

## Support

Open an issue in the [GitHub repository](https://github.com/xiaodong-wu/web-design-studio/issues).