Neue Skills, Referenzen & OpenWiki-Doku integriert

Umfangreiche Erweiterung der Skill-Bibliothek: Neue Skills für Humanisierung (Englisch/PT-BR), Design-Validierung, AI-SEO und Coolify-Deployment inkl. Regelwerke, Presets, Pattern-Referenzen, Testfälle und Automatisierungsskripte. Zusätzliche Skills für Revenue-Centric Design, Pier Cloud, OKF, Lebenslauf- und LinkedIn-Optimierung sowie zahlreiche Referenzdateien, Checklisten und YAML/JSON/Markdown-Templates. Einführung einer vollständigen OpenWiki-Dokumentation mit Architektur-, Domain- und Workflow-Beschreibungen, zentralem Index und automatisierten Updates. Modularer Aufbau, restriktive Lizenzen und umfassende Qualitäts- und Evaluationsmechanismen für alle neuen Inhalte.
2026-07-26 14:00:58 +02:00
parent 070727d5cd
commit 01046b01e4
202 changed files with 31290 additions and 0 deletions
--- a/.github/skills/design-md-validator/SKILL.md
+++ b/.github/skills/design-md-validator/SKILL.md
@@ -0,0 +1,230 @@
+---
+name: design-md-validator
+description: >
+  Validate DESIGN.md files against the official Google specification using the
+  `@google/design.md` CLI linter. Works with local files and remote URLs.
+  Use when the user wants to lint a DESIGN.md, check spec compliance, find
+  broken token references, verify WCAG contrast ratios, diff two versions,
+  export tokens to Tailwind or DTCG format, or audit a design system file
+  for structural correctness. Trigger on mentions of "validate DESIGN.md",
+  "lint DESIGN.md", "check my design.md", "design.md spec compliance",
+  "WCAG contrast check", "broken token references", "design token validation",
+  "export design tokens", "diff design systems", "design.md audit",
+  "@google/design.md", "npx design.md lint", "design system validation",
+  "frontmatter tokens", or any request to verify a DESIGN.md file.
+metadata:
+  author: https://ft.ia.br
+  version: "1.1"
+  date: 2026-07-18
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: product-verification
+  upstream:
+    spec: https://github.com/google-labs-code/design.md
+    cli: https://www.npmjs.com/package/@google/design.md
+    stitch-skills: https://github.com/google-labs-code/stitch-skills
+---
+
+# design-md-validator
+
+Validate, lint, diff, and export DESIGN.md files using the official Google
+`@google/design.md` CLI. Always uses the latest published version from npm —
+no vendored copy, always up-to-date with the spec.
+
+---
+
+## When to Use
+
+| Trigger | Action |
+|---|---|
+| User has a DESIGN.md file and wants validation | `lint` |
+| User wants to compare two versions | `diff` |
+| User wants to export tokens to Tailwind/DTCG | `export` |
+| User wants to see the current spec | `spec` |
+| User shares a URL to a raw DESIGN.md | Fetch → `lint` |
+| User asks "is my design.md valid?" | `lint` + interpret findings |
+
+---
+
+## Core Commands
+
+All commands use `npx @google/design.md` to ensure the latest version is always
+used. Never install globally — `npx` resolves from the public npm registry.
+
+### Lint (validate)
+
+```bash
+npx @google/design.md lint DESIGN.md
+```
+
+Output: JSON with `findings[]` and `summary { errors, warnings, infos }`.
+Exit code 1 if errors found, 0 otherwise.
+
+### Diff (compare versions)
+
+```bash
+npx @google/design.md diff DESIGN.md DESIGN-v2.md
+```
+
+Output: JSON with token-level changes (added, removed, modified) and regression flag.
+Exit codes: `0` no regression, `1` regression (errors in "after" > errors in "before"),
+`2` input failure (file not found or unreadable).
+
+### Export (to other formats)
+
+```bash
+# Tailwind v3 config
+npx @google/design.md export --format json-tailwind DESIGN.md
+
+# Tailwind v4 CSS theme
+npx @google/design.md export --format css-tailwind DESIGN.md
+
+# W3C Design Tokens (DTCG)
+npx @google/design.md export --format dtcg DESIGN.md
+
+# CSS custom properties (optional --prefix)
+npx @google/design.md export --format css-vars DESIGN.md
+npx @google/design.md export --format css-vars --prefix ds DESIGN.md
+```
+
+`css-vars` is available on main, ships in the next release — if the CLI
+rejects the format, npm is still on 0.3.0.
+
+### Spec (output the format specification)
+
+```bash
+npx @google/design.md spec
+npx @google/design.md spec --rules
+npx @google/design.md spec --rules-only --format json
+```
+
+---
+
+## Workflow
+
+### 1. Obtain the DESIGN.md
+
+**Local file:**
+```bash
+npx @google/design.md lint ./DESIGN.md
+```
+
+**From URL (fetch first):**
+```bash
+curl -sL <url> > /tmp/DESIGN.md && npx @google/design.md lint /tmp/DESIGN.md
+```
+
+**From stdin:**
+```bash
+cat DESIGN.md | npx @google/design.md lint -
+```
+
+### 2. Discover the Active Rule Set
+
+Before interpreting anything, check which rules the installed CLI actually
+runs — the rule set changes between releases, and the bundled references are
+a fallback, not the authoritative source:
+
+```bash
+npx @google/design.md spec --rules-only --format json
+```
+
+### 3. Run Lint
+
+```bash
+npx @google/design.md lint --format json DESIGN.md
+```
+
+### 4. Interpret Findings
+
+Parse the JSON output and report to the user:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| `error` | Spec violation — file is invalid | Must fix |
+| `warning` | Best practice violation — file is valid but suboptimal | Should fix |
+| `info` | Informational — suggestions for improvement | Nice to fix |
+
+### 5. Provide Actionable Fixes
+
+For each finding, explain:
+1. What the rule checks
+2. Why it matters
+3. How to fix it with a concrete code example
+
+### 6. Re-validate After Fixes
+
+After applying fixes, re-run lint to confirm the file passes.
+
+---
+
+## Linting Rules Reference
+
+Load `references/linting-rules.md` for the complete rule table when providing
+detailed explanations of lint failures.
+
+---
+
+## Token Schema Quick Reference
+
+Load `references/token-schema.md` for the complete YAML frontmatter schema
+when helping users author or fix their frontmatter tokens.
+
+---
+
+## Windows Compatibility
+
+On Windows/PowerShell, the `.md` suffix in the bin name collides with Markdown
+file associations. Use the `designmd` alias:
+
+```bash
+npx -p @google/design.md designmd lint DESIGN.md
+```
+
+---
+
+## Related Official Skills
+
+| Skill | Source | Purpose |
+|---|---|---|
+| `stitch-design-taste` | google-labs-code/stitch-skills | Generates DESIGN.md for Google Stitch |
+| `design-md` (Stitch plugin) | google-labs-code/stitch-skills | Analyzes Stitch projects → DESIGN.md |
+| `taste-design` (MCP) | mcpservers.org | MCP server for Stitch design extraction |
+
+Install the official Stitch skill for generation:
+```bash
+npx skills add https://github.com/google-labs-code/stitch-skills --skill design-md
+```
+
+---
+
+## Anti-Patterns
+
+- Never vendor or cache the CLI — always use `npx` for latest spec
+- Never manually parse YAML frontmatter when the linter can do it
+- Never guess at contrast ratios — let the linter compute them
+- Never assume section order is correct — let the linter verify
+- Never skip re-validation after fixes
+- Never assume the rule set from memory or from the bundled references —
+  confirm it at runtime with `spec --rules-only`
+
+---
+
+## Example Session
+
+```
+User: validate my DESIGN.md
+
+Agent:
+1. Reads the file
+2. Runs: npx @google/design.md spec --rules-only --format json
+3. Runs: npx @google/design.md lint --format json DESIGN.md
+4. Parses output
+5. Reports:
+   - summary: { errors: 0, warnings: 2, infos: 1 }
+   - WARNING: contrast-ratio — button textColor on backgroundColor is 3.8:1 (needs 4.5:1)
+   - WARNING: orphaned-tokens — color "accent-muted" defined but never used
+   - INFO: token-summary — 5 colors, 3 typography, 2 rounded, 2 spacing
+6. Suggests fixes with code
+7. Re-runs lint to confirm
+```
--- a/.github/skills/design-md-validator/references/linting-rules.md
+++ b/.github/skills/design-md-validator/references/linting-rules.md
@@ -0,0 +1,66 @@
+# Linting Rules — @google/design.md
+
+> Generated against npm 0.3.0 + main as of 2026-07-18. Authoritative source at
+> runtime: `npx @google/design.md spec --rules-only`.
+
+The linter runs nine rules against a parsed DESIGN.md in the published npm
+0.3.0 release; a tenth rule (`token-like-ignored`) has merged on main and
+ships in the next release. Each rule produces findings at a fixed severity
+level.
+
+## Rules Table
+
+| Rule | Severity | What it checks |
+|---|---|---|
+| `broken-ref` | error | Token references (`{colors.primary}`) that don't resolve to any defined token |
+| `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |
+| `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |
+| `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |
+| `token-summary` | info | Summary of how many tokens are defined in each section |
+| `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |
+| `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |
+| `section-order` | warning | Sections appear out of the canonical order defined by the spec |
+| `unknown-key` | warning | A top-level YAML key looks like a typo of a known schema key (e.g. `colours:` → `colors:`) |
+| `token-like-ignored` | warning | **Next release (on main since 2026-06-15, not in npm 0.3.0).** Warns when a top-level YAML key looks like a design-token map but is not part of the recognized export schema and will be silently ignored |
+
+## Section Order (canonical)
+
+Sections use `##` headings. They can be omitted, but those present must appear
+in this order:
+
+| # | Section | Aliases |
+|---|---|---|
+| 1 | Overview | Brand & Style |
+| 2 | Colors | |
+| 3 | Typography | |
+| 4 | Layout | Layout & Spacing |
+| 5 | Elevation & Depth | Elevation |
+| 6 | Shapes | |
+| 7 | Components | |
+| 8 | Do's and Don'ts | |
+
+## Consumer Behavior for Unknown Content
+
+| Scenario | Behavior |
+|---|---|
+| Unknown section heading | Preserve; do not error |
+| Unknown color token name | Accept if value is valid |
+| Unknown typography token name | Accept as valid typography |
+| Unknown component property | Accept with warning |
+| Duplicate section heading | Error; reject the file |
+
+## Exit Codes
+
+- `0` — No errors (warnings/info may be present)
+- `1` — Errors found (file is invalid per spec)
+
+## Programmatic API
+
+```typescript
+import { lint } from '@google/design.md/linter';
+
+const report = lint(markdownString);
+console.log(report.findings);       // Finding[]
+console.log(report.summary);        // { errors, warnings, infos }
+console.log(report.designSystem);   // Parsed DesignSystemState
+```
--- a/.github/skills/design-md-validator/references/token-schema.md
+++ b/.github/skills/design-md-validator/references/token-schema.md
@@ -0,0 +1,156 @@
+# Token Schema — DESIGN.md Spec (version alpha)
+
+The YAML front matter in a DESIGN.md file contains machine-readable design
+tokens. These are the normative values that agents use to generate code.
+
+## Top-Level Schema
+
+```yaml
+version: <string>          # optional, current: "alpha"
+name: <string>             # required
+description: <string>      # optional
+colors:
+  <token-name>: <Color>
+typography:
+  <token-name>: <Typography>
+rounded:
+  <scale-level>: <Dimension>
+spacing:
+  <scale-level>: <Dimension | number>
+components:
+  <component-name>:
+    <token-name>: <string | token reference>
+```
+
+## 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 font properties | See below |
+
+## Typography Object
+
+```yaml
+typography:
+  h1:
+    fontFamily: Public Sans
+    fontSize: 3rem
+    fontWeight: 700
+    lineHeight: 1.2
+    letterSpacing: -0.02em
+    fontFeature: "ss01"        # optional
+    fontVariation: "wght 700"  # optional
+  body-md:
+    fontFamily: Public Sans
+    fontSize: 1rem
+    fontWeight: 400
+    lineHeight: 1.5
+  label-caps:
+    fontFamily: Space Grotesk
+    fontSize: 0.75rem
+    fontWeight: 500
+    letterSpacing: 0.05em
+```
+
+Required fields per entry: `fontFamily`, `fontSize`.
+Optional fields: `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`.
+
+## Colors
+
+```yaml
+colors:
+  primary: "#1A1C1E"
+  secondary: "#6C7278"
+  tertiary: "#B8422E"
+  neutral: "#F7F5F2"
+  on-tertiary: "#FFFFFF"     # contrast pair for tertiary
+```
+
+The `primary` color is expected by the linter. Its absence triggers a
+`missing-primary` warning.
+
+## Rounded (border-radius scale)
+
+```yaml
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 16px
+```
+
+## Spacing
+
+```yaml
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+```
+
+## Components
+
+Components map a name to a group of sub-token properties:
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-tertiary}"
+    rounded: "{rounded.sm}"
+    padding: 12px
+  button-primary-hover:
+    backgroundColor: "{colors.tertiary-container}"
+```
+
+### Valid Component Properties
+
+`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`,
+`height`, `width`.
+
+### Variants
+
+Hover, active, pressed states are separate entries with a related key name:
+`button-primary-hover`, `button-primary-active`.
+
+## Token References
+
+References use curly braces with dot notation:
+
+```yaml
+components:
+  card:
+    backgroundColor: "{colors.neutral}"    # resolves to #F7F5F2
+    rounded: "{rounded.md}"                # resolves to 8px
+```
+
+Broken references (pointing to undefined tokens) trigger a `broken-ref` error.
+
+Since npm 0.3.0 (PR #103), token groups support nested sub-levels in the
+frontmatter — e.g. `colors.brand.primary` — and references use the full
+dotted path to the leaf token: `{colors.brand.primary}`.
+
+## File Structure Summary
+
+```
+---                         ← YAML front matter start
+name: "My Design System"
+colors: ...
+typography: ...
+rounded: ...
+spacing: ...
+components: ...
+---                         ← YAML front matter end
+
+## Overview                 ← Markdown prose sections
+...
+## Colors
+...
+## Typography
+...
+```
+
+The tokens are the normative values. The prose provides context for how to
+apply them.