# Project export: Gloss

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: Gloss turns the visual choices people can feel into Design DNA that agent can use to build consistent, on-brand design.
- Devpost: https://devpost.com/software/gloss-hepgax
- GitHub: https://github.com/txz8096/Gloss
- Video: https://www.youtube.com/embed/ymEA6D_hjoI?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — 勺 (7 commits)

## Devpost submission (written by the team)

### Inspiration

Many AI builders have strong visual instincts but lack the language to turn those instincts into a design system. They can look at two interfaces and immediately know which one feels right. What they cannot easily do is explain why in a way an AI coding agent can carry into the next screen. Humans see visual patterns. AI reads instructions. Gloss is the translation layer between the two.

### What it does

Gloss helps builders turn visual reactions into reusable design guidance through context, curation, and calibration. Users begin by describing the product they are building and what it needs to communicate. They then curate references and anti-references, choosing visual directions they want to carry forward and ones they want to avoid. Next, Gloss presents controlled A/B comparisons. Each comparison isolates one design decision, such as whether hierarchy should come from colour or typography, whether a surface should feel spacious or dense, or whether product proof should lead before personality. Users choose the direction that feels right and can explain their reasoning. Gloss turns those choices into Design DNA: a compact set of principles, trade-offs, anti-principles, and visual tokens. Builders can refine the final theme and export the result as agent-ready guidance.

### How we built it

I used ChatGPT as a thought partner to shape the product thesis, define the core workflow, and study adjacent tools. That research helped clarify the gap: existing products can generate a moodboard, extract tokens, or suggest a theme, but they do not help a user confirm the visual decisions an agent should make on future screens. I then used Codex to prototype the interface and iterate on the product flow. Given the BuildWeek timeline, I focused on proving the core interaction rather than building a full backend: a working visual prototype plus a Codex skill that can apply Gloss’s exported Design DNA to real UI code.

### Challenges we ran into

The hardest technical problem is rendering a user’s own uploaded screen in two genuinely different visual directions based on their previous curation. A screenshot does not contain the semantic structure, component states, or layout rules needed for a faithful redesign. Generating those variants also introduces model latency and cost. For this version, I focused on the more reliable handoff: Gloss captures the user’s decisions, then Codex uses those decisions to create or restyle a real screen in code.

### Accomplishments we're proud of

I’m proud that Gloss makes an abstract idea visible. The prototype shows that taste does not need to remain a private reaction or a vague prompt. It can become an inspectable system of choices that an agent can use. I’m also proud of the handoff concept: Gloss does not stop at inspiration. It produces guidance that can shape a screen the user has not seen yet.

### What we learned

Taste is not magic, and it is not limited to people with formal design training. It can be broken into decisions about hierarchy, density, grouping, personality, and proof. The important part is not teaching AI one universal definition of “good taste.” It is helping people teach an agent what feels right for their own product.

### What's next

I plan to keep building Gloss and package it as a Codex plugin. The goal is to make the workflow available inside the environment where many AI builders already create products. A future version will let users bring their product context, references, and calibrated Design DNA into Codex, then apply that guidance directly to their own codebase. It will support a fuller handoff from visual curation to implementation, so builders can create more consistent interfaces without having to translate every design decision into a new prompt.

## README (from the GitHub repository)

# Gloss

**Humans can feel when an interface is right. Coding agents need that judgment written down.**

Gloss turns visual taste into clear instructions that Codex can use when it builds the next screen.

## The problem

People often know what they like when they see it. They can point to a reference and say, “this feels right,” or reject a screen that looks generic. But that reaction is hard to hand to an AI coding agent.

A colour palette alone is not enough. An agent also needs to know what the product should emphasize, where character belongs, and what to avoid.

Without that context, each new screen can drift back toward the same generic defaults.

## What Gloss does

Gloss creates a reusable set of **guidelines** for one product. It helps a builder move from visual reactions to decisions an agent can apply consistently.

```text
Curate → Calibrate → Commit → Apply
```

1. **Curate** — Collect references and anti-references. Mark what should carry forward and what should be avoided.
2. **Calibrate** — Compare two controlled directions. Choose the option that better expresses the product’s intended feeling and explain why when useful.
3. **Commit** — Save the result as guidelines: principles, anti-principles, trade-offs, and tokens.
4. **Apply** — Use the included `gloss-apply` Codex skill to turn those guidelines into a real new or updated screen in a codebase.

Gloss is not trying to generate a different product concept each time. It preserves the product’s task and structure, then gives the implementation a consistent visual point of view.

## Concrete example

Imagine a builder is creating a project-management tool for a small team.

### What they give Gloss

**Product context**

> Help a small team understand what needs attention today. It should feel calm, capable, and direct — never like a flashy productivity app.

**Visual choices**

- Reference: a warm, editorial interface with clear type and generous space.
- Reference: a practical dashboard with strong task hierarchy.
- Anti-reference: glossy gradient cards and decorative charts with no job.
- Calibration choice: use typography and position to establish hierarchy before adding accent colour.

### What Gloss produces

`guidelines.md`

```md
# Guidelines

## Intent
Make daily work feel calm and legible, while keeping the next action obvious.

## Principles
- Let hierarchy come from type, spacing, and position before colour.
- Keep the working surface quiet; reserve warmth for meaningful choices.
- Put useful task evidence close to the decision it supports.

## Anti-principles
- Do not use glossy gradients, decorative charts, or floating cards without a task-related purpose.

## Trade-offs
- Dense task views may reduce editorial spacing, but must keep one clear primary action.
```

`tokens.json`

```json
{
  "color": {
    "background": "#F2E9DF",
    "foreground": "#28211C",
    "accent": "#E3705E"
  },
  "surface": {
    "radius": "12px"
  }
}
```

### What Codex produces with the skill

The builder asks:

```text
Use $gloss-apply to create an empty state for the team’s task dashboard.
Read gloss/guidelines.md and gloss/tokens.json. Preserve the existing task flow.
```

Codex then produces working UI code for the empty state. It applies the hierarchy, spacing, surfaces, and boundaries in the guidelines to a screen that was not part of the original curation.

## Install `gloss-apply` in Codex

The skill is a local Codex skill: install it once, then invoke it in any compatible project with `$gloss-apply`.

1. Clone this repository:

   ```bash
   git clone https://github.com/txz8096/Gloss.git
   ```

2. Copy the skill into Codex's local skills directory:

   ```bash
   mkdir -p ~/.codex/skills
   cp -R Gloss/.agents/skills/gloss-apply ~/.codex/skills/gloss-apply
   ```

3. Restart Codex, or begin a new task so it discovers the skill.

To update the skill later, pull the repository changes and repeat step 2. The source is [`.agents/skills/gloss-apply`](.agents/skills/gloss-apply).

### What you provide

Put the exported Gloss files in the project you want Codex to change:

```text
your-project/
├── gloss/
│   ├── guidelines.md  # Required: intent, principles, boundaries, trade-offs
│   └── tokens.json    # Optional: colour, type, surface values
└── src/
```

Then give Codex a specific implementation target: a component, route, or screen to create or restyle. `guidelines.md` tells Codex how to make visual decisions; `tokens.json` supplies reusable values. The schema is defined in [the export contract](.agents/skills/gloss-apply/references/export-contract.md).

### What you get back

| Output | What to expect |
|---|---|
| Working code | A changed component, route, or new screen in the target project. |
| Applied direction | Hierarchy, density, type, grouping, surfaces, and boundaries reflect the guidelines, not only their colours. |
| Brief rationale | A concise account of which principles informed the main decisions and any trade-off that could not be preserved. |
| Validation | A rendered or tested result when the target project provides a local validation path. |

The skill preserves existing product behavior, content, accessibility, and information architecture unless you explicitly ask to change them. It does not invent a product concept or promise pixel-perfect reproduction from a screenshot.

### Copy-and-paste requests

Restyle an existing screen:

```text
Use $gloss-apply to restyle src/routes/ProjectOverview.tsx.
Read gloss/guidelines.md and gloss/tokens.json. Preserve the existing task flow,
copy, and data states. Render the result locally if this project supports it.
```

Create a new state within an existing product:

```text
Use $gloss-apply to create the empty state for the team task dashboard.
Read gloss/guidelines.md and gloss/tokens.json. Reuse existing components and
preserve the dashboard's navigation and task flow.
```

Review a screen that feels visually inconsistent:

```text
Use $gloss-apply to review and improve src/components/ActivityFeed.tsx.
Read gloss/guidelines.md. Keep the interaction behavior unchanged. Explain which
Gloss principles the current screen violates, then implement the highest-impact fixes.
```

## Try the prototype

**[Open the live prototype](https://www.melissatang.com/gloss-prototype)** — no install, runs in the browser. It demonstrates the Gloss flow from product context through curation, calibration, and a final visual-system handoff.

You can also open [`prototype.html`]([https://www.melissatang.com/gloss-prototype]) from a local clone; it is a single self-contained file.

For a working handoff you can copy, see [`examples/project-dashboard`](examples/project-dashboard).

## Current scope

This repository contains the interactive Gloss prototype, the agent handoff contract, and a copyable example export. The prototype runs the full loop: product context, curation, calibration, and a commit step that produces `guidelines.md` and `tokens.json` alongside a before/after view of the committed system applied to your own screenshot.

The next step is running `gloss-apply` against a real sample application and tightening the export contract based on what the agent actually needs.

## Repository layout

```text
.
├── prototype.html                 # Interactive product prototype
├── .agents/skills/gloss-apply/    # Reusable Codex skill
├── examples/project-dashboard/    # Copyable guidelines handoff
└── docs/                          # Product and architecture notes
```


## Detected evidence (automated analysis)

Indexed codebase: 9 recognized source files, 139 KB.
- HTML (language) — detected in the code

## Codebase structure (from repository index)

### Files (12 of 12)

```
.agents/skills/gloss-apply/agents/openai.yaml
.agents/skills/gloss-apply/references/export-contract.md
.agents/skills/gloss-apply/SKILL.md
.gitignore
docs/architecture.md
docs/product-spec.md
examples/project-dashboard/design-dna.md
examples/project-dashboard/README.md
examples/project-dashboard/tokens.json
LICENSE
prototype.html
README.md
```

### Dependencies

No dependency index available.

### Recent commits (newest first)

- Merge pull request #1 from txz8096/codex/add-prd
- Merge main into codex/add-prd
- Package Gloss skill for GitHub
- Add visual system prototype
- Add visual system prototype
- add PRD
- Initial commit

## Key source files (fetched from GitHub, selected and truncated for size)

### docs/architecture.md

```markdown
# Architecture

The current repository is intentionally dependency-free.

- `prototype.html` is a self-contained interactive demonstration of the Gloss flow.
- `.agents/skills/gloss-apply` is the Codex skill that reads a Gloss export and applies it to code.
- `examples/project-dashboard` is a generic handoff a user can inspect or copy into another project.

The prototype demonstrates the interaction model. The skill is the implementation handoff: it converts a chosen visual direction into working UI while preserving existing content, behavior, accessibility, and structure.

```

### docs/product-spec.md

```markdown
# Gloss product specification

## Purpose

Gloss turns a builder's visual judgment into durable instructions that an AI coding agent can apply to future product screens.

## Core loop

```text
Curate references → calibrate visual trade-offs → commit Design DNA → apply it in code
```

1. **Curate** reference and anti-reference signals alongside product context.
2. **Calibrate** with controlled comparisons that each test one visual tension.
3. **Commit** a Design DNA export: intent, principles, anti-principles, trade-offs, and optional tokens.
4. **Apply** the export with the included `gloss-apply` skill to a real component or screen.

## Product boundaries

- Preserve the product's information architecture and task flow.
- Treat anti-principles as hard boundaries, not optional styling suggestions.
- Use tokens as values and Design DNA as the decision-making layer.
- Do not infer pixel-perfect implementation details from a screenshot-only reference.

## Export contract

Every minimal handoff includes:

- A one-sentence intent describing the product feeling and job.
- Imperative visual principles with reasons.
- Anti-principles that state what the implementation must avoid.
- Trade-offs that explain how principles adapt on dense or task-heavy surfaces.
- Optional tokens for colour, typography, and component surfaces.

The complete machine-facing schema is in [the export contract](../.agents/skills/gloss-apply/references/export-contract.md).

```

### .agents/skills/gloss-apply/agents/openai.yaml

```yaml
interface:
  display_name: "Gloss Apply"
  short_description: "Apply exported Gloss Design DNA to a real product screen."
  default_prompt: "Use $gloss-apply to apply the exported Gloss design system to this screen."

```

[3 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]