better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-design-md.md

@@ -1,238 +0,0 @@
----
-title: "Design Md — Author/validate/export Google's DESIGN.md token spec files"
-sidebar_label: "Design Md"
-description: "Author/validate/export Google's DESIGN.md token spec files"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Design Md
-
-Author/validate/export Google's DESIGN.md token spec files.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/creative\design-md` |
-| Version | `1.1.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `design`, `design-system`, `tokens`, `ui`, `accessibility`, `wcag`, `tailwind`, `dtcg`, `google` |
-| Related skills | [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/optional/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# DESIGN.md Skill
-
-DESIGN.md is Google's open spec (Apache-2.0, `google-labs-code/design.md`) for
-describing a visual identity to coding agents. One file combines:
-
-- **YAML front matter** — machine-readable design tokens (normative values)
-- **Markdown body** — human-readable rationale, organized into canonical sections
-
-Tokens give exact values. Prose tells agents *why* those values exist and how to
-apply them. The CLI (`npx @google/design.md`) lints structure + WCAG contrast,
-diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.
-
-## When to use this skill
-
-- User asks for a DESIGN.md file, design tokens, or a design system spec
-- User wants consistent UI/brand across multiple projects or tools
-- User pastes an existing DESIGN.md and asks to lint, diff, export, or extend it
-- User asks to port a style guide into a format agents can consume
-- User wants contrast / WCAG accessibility validation on their color palette
-
-For purely visual inspiration or layout examples, use `popular-web-designs`
-instead. For *process and taste* when designing a one-off HTML artifact
-from scratch (prototype, deck, landing page, component lab), use
-`claude-design`. This skill is for the *formal spec file* itself.
-
-## File anatomy
-
-```md
----
-version: alpha
-name: Heritage
-description: Architectural minimalism meets journalistic gravitas.
-colors:
-  primary: "#1A1C1E"
-  secondary: "#6C7278"
-  tertiary: "#B8422E"
-  neutral: "#F7F5F2"
-typography:
-  h1:
-    fontFamily: Public Sans
-    fontSize: 3rem
-    fontWeight: 700
-    lineHeight: 1.1
-    letterSpacing: "-0.02em"
-  body-md:
-    fontFamily: Public Sans
-    fontSize: 1rem
-rounded:
-  sm: 4px
-  md: 8px
-  lg: 16px
-spacing:
-  sm: 8px
-  md: 16px
-  lg: 24px
-components:
-  button-primary:
-    backgroundColor: "{colors.tertiary}"
-    textColor: "#FFFFFF"
-    rounded: "{rounded.sm}"
-    padding: 12px
-  button-primary-hover:
-    backgroundColor: "{colors.primary}"
----
-
-## Overview
-
-Architectural Minimalism meets Journalistic Gravitas...
-
-## Colors
-
-- **Primary (#1A1C1E):** Deep ink for headlines and core text.
-- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
-
-## Typography
-
-Public Sans for everything except small all-caps labels...
-
-## Components
-
-`button-primary` is the only high-emphasis action on a page...
-```
-
-## Token types
-
-| Type | Format | Example |
-|------|--------|---------|
-| Color | any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
-| Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
-| Token reference | `{path.to.token}` | `{colors.primary}` |
-| Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | see above |
-
-Component property whitelist: `backgroundColor`, `textColor`, `typography`,
-`rounded`, `padding`, `size`, `height`, `width`. Variants (hover, active,
-pressed) are **separate component entries** with related key names
-(`button-primary-hover`), not nested.
-
-## Canonical section order
-
-Sections are optional, but present ones should appear in this order. The
-linter flags out-of-order sections (`section-order`, warning) and duplicate
-headings — consumers per the spec reject duplicates, so fix both before
-returning the file.
-
-1. Overview (alias: Brand & Style)
-2. Colors
-3. Typography
-4. Layout (alias: Layout & Spacing)
-5. Elevation & Depth (alias: Elevation)
-6. Shapes
-7. Components
-8. Do's and Don'ts
-
-Unknown sections are preserved, not errored. Unknown token names are accepted
-if the value type is valid. Unknown component properties produce a warning.
-
-## Workflow: authoring a new DESIGN.md
-
-1. **Ask the user** (or infer) the brand tone, accent color, and typography
-   direction. If they provided a site, image, or vibe, translate it to the
-   token shape above.
-2. **Write `DESIGN.md`** in their project root using `write_file`. Always
-   include `name:` and `colors:`; other sections optional but encouraged.
-3. **Use token references** (`{colors.primary}`) in the `components:` section
-   instead of re-typing hex values. Keeps the palette single-source.
-4. **Lint it** (see below). Fix any broken references or WCAG failures
-   before returning.
-5. **If the user has an existing project**, also write Tailwind or DTCG
-   exports next to the file (`tailwind.theme.json`, `tokens.json`).
-
-## Workflow: lint / diff / export
-
-The CLI is `@google/design.md` (Node). Use `npx` — no global install needed.
-
-```bash
-# Validate structure + token references + WCAG contrast
-npx -y @google/design.md lint DESIGN.md
-
-# Compare two versions, fail on regression (exit 1 = regression)
-npx -y @google/design.md diff DESIGN.md DESIGN-v2.md
-
-# Export to Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
-npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
-
-# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
-npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css
-
-# Export to W3C DTCG (Design Tokens Format Module) JSON
-npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json
-
-# Print the spec itself — useful when injecting into an agent prompt
-npx -y @google/design.md spec --rules-only --format json
-```
-
-All commands accept `-` for stdin. `lint` returns exit 1 on errors (warnings
-alone exit 0). `export` exits 0 on a successful export regardless of lint
-findings in the source — run `lint` separately to gate on those. Output is
-JSON by default; parse it if you need to report findings structurally.
-
-On Windows, the `design.md` bin name can collide with the `.md` file
-association (silent no-op or the file opens in an editor). Use the dot-free
-alias: `npx -y -p @google/design.md designmd lint DESIGN.md`.
-
-### Lint rule reference (the 9 rules, as of CLI 0.3.0)
-
-- `broken-ref` (error) — `{colors.missing}` points at a non-existent token
-- `contrast-ratio` (warning) — component `textColor` vs `backgroundColor`
-  below WCAG AA (4.5:1)
-- `missing-primary` (warning) — colors defined but no `primary` token
-- `missing-typography` (warning) — colors defined but no typography tokens
-- `orphaned-tokens` (warning) — color tokens never referenced by a component
-- `section-order` (warning) — sections out of the canonical order
-- `unknown-key` (warning) — top-level YAML key that looks like a typo of a
-  schema key (`colours:` → `colors:`); custom extension keys stay silent
-- `token-summary`, `missing-sections` (info) — counts and absent optional
-  sections
-
-When the user cares about accessibility, call this out explicitly in your
-summary — WCAG findings are the most load-bearing reason to use the CLI.
-
-## Pitfalls
-
-- **Don't nest component variants.** `button-primary.hover` is wrong;
-  `button-primary-hover` as a sibling key is right.
-- **Hex colors must be quoted strings.** YAML will otherwise choke on `#` or
-  truncate values like `#1A1C1E` oddly.
-- **Negative dimensions need quotes too.** `letterSpacing: -0.02em` parses as
-  a YAML flow — write `letterSpacing: "-0.02em"`.
-- **Section order matters even though the linter only warns.** If the user
-  gives you prose in a random order, reorder it to match the canonical list
-  before saving — spec-compliant consumers expect it.
-- **Typography sub-property typos are silently dropped.** As of CLI 0.3.0 a
-  typo like `fontwight:` produces no finding and the value vanishes from
-  exports — double-check sub-property names against the schema
-  (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`,
-  `fontFeature`, `fontVariation`).
-- **`version: alpha` is the current spec version** (as of Jul 2026, CLI
-  0.3.0). The spec is marked alpha — watch for breaking changes.
-- **Token references resolve by dotted path.** `{colors.primary}` works;
-  `{primary}` does not.
-
-## Spec source of truth
-
-- Repo: https://github.com/google-labs-code/design.md (Apache-2.0)
-- CLI: `@google/design.md` on npm
-- License of generated DESIGN.md files: whatever the user's project uses;
-  the spec itself is Apache-2.0.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-excalidraw.md

@@ -1,212 +0,0 @@
----
-title: "Excalidraw — Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)"
-sidebar_label: "Excalidraw"
-description: "Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Excalidraw
-
-Hand-drawn Excalidraw JSON diagrams (arch, flow, seq).
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/creative/excalidraw` |
-| Version | `1.0.1` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Excalidraw`, `Diagrams`, `Flowcharts`, `Architecture`, `Visualization`, `JSON` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Excalidraw Diagram Skill
-
-Create diagrams by writing standard Excalidraw element JSON and saving as `.excalidraw` files. These files can be drag-and-dropped onto [excalidraw.com](https://excalidraw.com) for viewing and editing. No accounts, no API keys, no rendering libraries -- just JSON.
-
-## When to use
-
-Generate `.excalidraw` files for architecture diagrams, flowcharts, sequence diagrams, concept maps, and more. Files can be opened at excalidraw.com or uploaded for shareable links.
-
-## Workflow
-
-1. **Load this skill** (you already did)
-2. **Write the elements JSON** -- an array of Excalidraw element objects
-3. **Save the file** using `write_file` to create a `.excalidraw` file
-4. **Optionally upload** for a shareable link using `scripts/upload.py` via `terminal`
-
-### Saving a Diagram
-
-Wrap your elements array in the standard `.excalidraw` envelope and save with `write_file`:
-
-```json
-{
-  "type": "excalidraw",
-  "version": 2,
-  "source": "hermes-agent",
-  "elements": [ ...your elements array here... ],
-  "appState": {
-    "viewBackgroundColor": "#ffffff"
-  }
-}
-```
-
-Save to any path, e.g. `~/diagrams/my_diagram.excalidraw`.
-
-### Uploading for a Shareable Link
-
-Run the upload script (located in this skill's `scripts/` directory) via terminal:
-
-```bash
-python skills/creative/excalidraw/scripts/upload.py ~/diagrams/my_diagram.excalidraw
-```
-
-This uploads to excalidraw.com (no account needed) and prints a shareable URL. Requires the `cryptography` pip package (`pip install cryptography`).
-
----
-
-## Element Format Reference
-
-### Required Fields (all elements)
-`type`, `id` (unique string), `x`, `y`, `width`, `height`
-
-### Defaults (skip these -- they're applied automatically)
-- `strokeColor`: `"#1e1e1e"`
-- `backgroundColor`: `"transparent"`
-- `fillStyle`: `"solid"`
-- `strokeWidth`: `2`
-- `roughness`: `1` (hand-drawn look)
-- `opacity`: `100`
-
-Canvas background is white.
-
-### Element Types
-
-**Rectangle**:
-```json
-{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }
-```
-- `roundness: { "type": 3 }` for rounded corners
-- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` for filled
-
-**Ellipse**:
-```json
-{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }
-```
-
-**Diamond**:
-```json
-{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }
-```
-
-**Labeled shape (container binding)** -- create a text element bound to the shape:
-
-> **WARNING:** Do NOT use `"label": { "text": "..." }` on shapes. This is NOT a valid
-> Excalidraw property and will be silently ignored, producing blank shapes. You MUST
-> use the container binding approach below.
-
-The shape needs `boundElements` listing the text, and the text needs `containerId` pointing back:
-```json
-{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
-  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
-  "boundElements": [{ "id": "t_r1", "type": "text" }] },
-{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
-  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
-  "textAlign": "center", "verticalAlign": "middle",
-  "containerId": "r1", "originalText": "Hello", "autoResize": true }
-```
-- Works on rectangle, ellipse, diamond
-- Text is auto-centered by Excalidraw when `containerId` is set
-- The text `x`/`y`/`width`/`height` are approximate -- Excalidraw recalculates them on load
-- `originalText` should match `text`
-- Always include `fontFamily: 1` (Virgil/hand-drawn font)
-
-**Labeled arrow** -- same container binding approach:
-```json
-{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
-  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
-  "boundElements": [{ "id": "t_a1", "type": "text" }] },
-{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
-  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
-  "textAlign": "center", "verticalAlign": "middle",
-  "containerId": "a1", "originalText": "connects", "autoResize": true }
-```
-
-**Standalone text** (titles and annotations only -- no container):
-```json
-{ "type": "text", "id": "t1", "x": 150, "y": 138, "text": "Hello", "fontSize": 20,
-  "fontFamily": 1, "strokeColor": "#1e1e1e", "originalText": "Hello", "autoResize": true }
-```
-- `x` is the LEFT edge. To center at position `cx`: `x = cx - (text.length * fontSize * 0.5) / 2`
-- Do NOT rely on `textAlign` or `width` for positioning
-
-**Arrow**:
-```json
-{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
-  "points": [[0,0],[200,0]], "endArrowhead": "arrow" }
-```
-- `points`: `[dx, dy]` offsets from element `x`, `y`
-- `endArrowhead`: `null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"`
-- `strokeStyle`: `"solid"` (default) | `"dashed"` | `"dotted"`
-
-### Arrow Bindings (connect arrows to shapes)
-
-```json
-{
-  "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 150, "height": 0,
-  "points": [[0,0],[150,0]], "endArrowhead": "arrow",
-  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
-  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
-}
-```
-
-`fixedPoint` coordinates: `top=[0.5,0]`, `bottom=[0.5,1]`, `left=[0,0.5]`, `right=[1,0.5]`
-
-### Drawing Order (z-order)
-- Array order = z-order (first = back, last = front)
-- Emit progressively: background zones → shape → its bound text → its arrows → next shape
-- BAD: all rectangles, then all texts, then all arrows
-- GOOD: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
-- Always place the bound text element immediately after its container shape
-
-### Sizing Guidelines
-
-**Font sizes:**
-- Minimum `fontSize`: **16** for body text, labels, descriptions
-- Minimum `fontSize`: **20** for titles and headings
-- Minimum `fontSize`: **14** for secondary annotations only (sparingly)
-- NEVER use `fontSize` below 14
-
-**Element sizes:**
-- Minimum shape size: 120x60 for labeled rectangles/ellipses
-- Leave 20-30px gaps between elements minimum
-- Prefer fewer, larger elements over many tiny ones
-
-### Color Palette
-
-See `references/colors.md` for full color tables. Quick reference:
-
-| Use | Fill Color | Hex |
-|-----|-----------|-----|
-| Primary / Input | Light Blue | `#a5d8ff` |
-| Success / Output | Light Green | `#b2f2bb` |
-| Warning / External | Light Orange | `#ffd8a8` |
-| Processing / Special | Light Purple | `#d0bfff` |
-| Error / Critical | Light Red | `#ffc9c9` |
-| Notes / Decisions | Light Yellow | `#fff3bf` |
-| Storage / Data | Light Teal | `#c3fae8` |
-
-### Tips
-- Use the color palette consistently across the diagram
-- **Text contrast is CRITICAL** -- never use light gray on white backgrounds. Minimum text color on white: `#757575`
-- Do NOT use emoji in text -- they don't render in Excalidraw's font
-- For dark mode diagrams, see `references/dark-mode.md`
-- For larger examples, see `references/examples.md`