DESIGN.mdBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

---
name: Heritage
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
label-caps:
fontFamily: Space Grotesk
fontSize: 0.75rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

npx @google/design.md lint DESIGN.md

{
"findings": [
{
"severity": "warning",
"path": "components.button-primary",
"message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
}
],
"

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: agent-dx-cli-scale
description: A scoring scale for evaluating how well a CLI is designed for AI agents, based on the "Rewrite Your CLI for AI Agents" principles.
---

# Agent DX CLI Scale

Use this skill to **evaluate any CLI** against the principles of agent-first design. Score each axis from 0–3, then sum for a total between 0–21.

> Human DX optimizes for discoverability and forgiveness.
> Agent DX optimizes for predictability and defense-in-depth.
> — [You Need to Rewrite Your CLI for AI Agents](/posts/rewrite-your-cli-for-ai-agents)

---

## Scoring Axes

### 1. Machine-Readable Output

Can an agent parse the CLI's output without heuristics?

| Score | Criteria                                                                                              |
| ----- | ----------------------------------------------------------------------------------------------------- |
| 0     | Human-only output (tables, color codes, prose). No structured format available.                       |
| 1     | `--output json` or equivalent exists but is incomplete or inconsistent across commands.               |
| 2     | Consistent JSON output across all commands. Errors also return structured JSON.                       |
| 3     | NDJSON streaming for paginated results. Structured output is the default in non-TTY (piped) contexts. |

### 2. Raw Payload Input

Can an agent send the full API payload without translation through bespoke flags?

| Score | Criteria                                                                                                                              |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | Only bespoke flags. No way to pass structured input.                                                                                  |
| 1     | Accepts `--json` or stdin JSON for some commands, but most require flags.                                                             |
| 2     | All mutating commands accept a raw JSON payload that maps directly to the underlying API schema.                                      |
| 3     | Raw payload is first-class alongside convenience flags. The agent can use the API schema as documentation with zero translation loss. |

### 3. Schema Introspection

Can an agent discover what the CLI accepts at runtime without pre-stuffed documentation?

| Score | Criteria                                                                                                                                                |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | Only `--help` text. No machine-readable schema.                                                                                                         |
| 1     | `--help --json` or a `describe` command for some surfaces, but incomplete.                                                                              |
| 2     | Full schema introspection for all commands — params, types, required fields — as JSON.                                                                  |
| 3     | Live, runtime-resolved schemas (e.g., from a discovery document) that always reflect the current API version. Includes scopes, enums, and nested types. |

### 4. Context Window Discipline

Does the CLI help agents control response size to protect their context window?

| Score | Criteria                                                                                                                                                    |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | Returns full API responses with no way to limit fields or paginate.                                                                                         |
| 1     | Supports `--fields` or field masks on some commands.                                                                                                        |
| 2     | Field masks on all read commands. Pagination with `--page-all` or equivalent.                                                                               |
| 3     | Streaming pagination (NDJSON per page). Explicit guidance in context/skill files on field mask usage. The CLI actively protects the agent from token waste. |

### 5. Input Hardening

Does the CLI defend against the specific ways agents fail (hallucinations, not typos)?

| Score | Criteria                                                                                                                                                                                |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | No input validation beyond basic type checks.                                                                                                                                           |
| 1     | Validates some inputs, but does not cover agent-specific hallucination patterns (path traversals, embedded query params, double encoding).                                              |
| 2     | Rejects control characters, path traversals (`../`), percent-encoded segments (`%2e`), and embedded query params (`?`, `#`) in resource IDs.                                            |
| 3     | Comprehensive hardening: all of the above, plus output path sandboxing to CWD, HTTP-layer percent-encoding, and an explicit security posture — _"The agent is not a trusted operator."_ |

### 6. Safety Rails

Can agents validate before acting, and are responses sanitized against prompt injection?

| Score | Criteria                

BLOCKgrade D · trust 67/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

declared (5 observation(s))

Network

none-observed

Shell

declared (6 observation(s))

Dependencies

not all pinned

Secrets in source

none-found

Findings (12)

const importCheck = exec(`node ${smokeFile}`);

const sanityCheck = exec(`node ${sanityFile}`);

const cliCheck = exec(`node ${cliIndex} --help`);

const specCheck = exec(`node ${cliIndex} spec`);

const fn = new Function(...Object.keys(scope), `return ${expr}`);

import type { DesignSystemState } from '../../model/spec.js';

import { VALID_COMPONENT_SUB_TOKENS } from '../../model/spec.js';

import type { DesignSystemState, ResolvedColor, ResolvedValue } from '../../model/spec.js';

import { contrastRatio } from '../../model/handler.js';

import type { DesignSystemState } from '../../model/spec.js';

@types/node, bun-types, turbo, typescript

citty, remark-frontmatter, remark-mdx, remark-parse, remark-stringify, unified, unist-util-visit, yaml

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: DESIGN.md](https://modelsatlas.com/skills/google-labs-code/tdd-red-green-refactor/badge.svg)](https://modelsatlas.com/skills/google-labs-code/tdd-red-green-refactor/)

Not your listing, or something out of date? Claim or update your listing.