Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

component-docs-page

/component-docs-page

Prowadzi przez listę kontrolną publikacji komponentu na stronie dokumentacji, od nowej strony po sekcje i powiązane elementy.

Repozytorium
forge ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
11.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Prowadzi przez listę kontrolną publikacji komponentu na stronie dokumentacji, od nowej strony po sekcje i powiązane elementy.

Wyzwalacze z opisu

add X to the docs sitecreate the docs page for a new componentdocument the new X componentadd a usage page for X
Oryginalny opis (EN)

This skill should be used when the user asks to "add X to the docs site", "create the docs page for a new component", "document the new X component", "add a usage page for X", or otherwise discusses publishing a component (new, migrated, or undocumented) on the `docs/` site. It is the end-to-end checklist and hands off to component-docs-header, forge-blocks-authoring, and docs-anatomy-diagram for the individual pieces.

Jak działa

  1. 1. Blocks first, on their own branch
  2. 2. usage.mdx: frontmatter
  3. 3. usage.mdx: sections, in this order
  4. 4. accessibility.mdx
  5. 5. Register what the page renders
  6. 6. Automatic, but check them
  7. 7. All components page
  8. 8. Regenerate the Forge Design skill
  9. 9. Verify
  10. Done when
Sekcje z nagłówków SKILL.md, w oryginale · 105 linii, 1 112 słów
Podgląd SKILL.md
---
name: component-docs-page
description: This skill should be used when the user asks to "add X to the docs site", "create the docs page for a new component", "document the new X component", "add a usage page for X", or otherwise discusses publishing a component (new, migrated, or undocumented) on the `docs/` site. It is the end-to-end checklist and hands off to component-docs-header, forge-blocks-authoring, and docs-anatomy-diagram for the individual pieces.
---

# Component Docs Page

A component is on the docs site when every item below is done. Work through them in order and report which are done, skipped (with the reason), or blocked. Reference pages: `tabs/` (Overview, variants, a11y with a keyboard table) and `structured-card/` (adds an anatomy diagram).

Everything lives in `docs/src/content/components/<slug>/`. The slug must be the primary tag name without `forge-`, because that's how the API tab finds the component in `custom-elements.json` (`forge-date-picker` → `date-picker`). A slug that doesn't match shows "coming soon" on the API tab; `tabs` (tag `forge-tab-bar`) currently has this problem.

## 1. Blocks first, on their own branch

Every demo on the page comes from a block, so the blocks have to exist and be deployed before the page can point at them.

- Use the **`forge-blocks-authoring`** skill: one block per Storybook story in `packages/forge/src/stories/components/<name>/`, starting with a `demo` block for "Basic usage".
- Branch off `main` for the blocks, separate from the docs branch. A `blockUrl` is checked against the live block manifest, so it only resolves once the blocks PR is merged and deployed.
- Until then, leave `blockUrl` off an `<Example>`. The skill generator derives the block ID from the section heading (`## Basic usage` → `components/<slug>/demo/demo`, `## Vertical` → `components/<slug>/vertical/vertical`) and reports it as PENDING instead of failing. Name variant headings so they derive the block IDs you created.

## 2. `usage.mdx`: frontmatter

Every field must match `docs/src/content.config.ts`:

```yaml
---
title: Tabs
description: One sentence, present tense, starting with the component name.
status: stable          # stable | beta | deprecated | planned
source: core            # core | block
category: navigation    # a key in docs/src/data/component-categories.ts
storybookId: components-tabs--demo   # optional; adds the Playground tab
---
```

`category` places the component in the sidenav and on the All components page. Nothing else needs registering for navigation.

## 3. `usage.mdx`: sections, in this order

| Section | Required | Contents |
| --- | --- | --- |
| Header | Yes | The live demo at the top, in its own `header.astro` rendered as `<Header />`. Use the **`component-docs-header`** skill. Never write `<ComponentHeader>` inline in the MDX: the All components page builds its thumbnail from `header.astro`, so an inline header leaves the card blank. |
| `## Overview` | Yes | One or two paragraphs: what it is, what it's for, and what it's typically paired with. No API names. |
| `## Usage` | Yes | One paragraph: the key elements and properties in backticks, when to use it, and when to use something else instead (link to that component's usage page). |
| `## Slot locations` | When it has named slots or regions | Numbered anatomy diagram. Use the **`docs-anatomy-diagram`** skill. |
| `## Rules` | Yes | `<Rules>` with a `do` and a `dont` `<Rule>`, 3–6 short imperative rules each. |
| `## Basic usage` | Yes | One sentence, then `<Example description="..." blockUrl="..." />` for the `demo` block. |
| `## <Variant>` | One per block | One or two sentences on when and how, then that block's `<Example>`. Plain fenced `html` code is fine for a pattern with no visual difference worth a live demo. |

- Every `<Example>` needs a string `description`. The skill build fails without one.
- Link other components with `` <a href={`${import.meta.env.BASE_URL}components/<slug>/usage/`}> ``, not root-relative markdown links.
- Card, drawer and other titles in prose follow the heading-style rules: page and dialog titles `text-heading4`, card and drawer titles `text-heading3`. Never prescribe the `h1`–`h6` element.

## 4. `accessibility.mdx`

Without this file the Accessibility tab shows "coming soon". It has no frontmatter and no header, just `##` sections. Include the ones that apply:

- `## Keyboard interaction`: a `| Key | Action |` table for anything focusable.
- `## Screen reader behavior`: roles, live regions, and what's announced.
- `## Labeling`: how to give it an accessible name, and the ARIA the consumer must still supply.
- Component-specific sections where they help (for example, `## Color and contrast` for a badge, `## Heading level` for a structured card).

Describe what the component handles automatically and what the consumer has to wire up. Get roles, keys and attributes from the component source and `get_component_docs`, not memory.

## 5. Register what the page renders

Add every Forge component and icon used in the header, the anatomy diagram, and any inline markup to `docs/src/scripts/forge-components.ts`: side-effect imports (`import "@tylertech/forge/<name>";`) and `IconRegistry.define([...])`. Unregistered components don't upgrade and unregistered icons render blank. Blocks render in their own iframe and don't need this.

## 6. Automatic, but check them

- **API tab:** generated from `@tylertech/forge/custom-elements.json`. If it's empty, the slug doesn't match the tag name, or the component isn't in the installed Forge build yet.
- **Playground tab:** appears when `storybookId` is set. Confirm the story ID exists.
- **Sidenav:** comes from the collection and `category`.

## 7. All components page

The card on `docs/src/pages/components/index.astro` takes its title and description from the frontmatter, and its thumbnail from `<slug>/header.astro`, loaded with `import.meta.glob`. The card still appears without a header file, but with no visual. Confirm:

- `docs/src/content/components/<slug>/header.astro` exists and forwards the `thumbnail` prop to `ComponentHeader`.
- Every component in the header is registered (step 5), or the thumbnail renders empty.
- The demo is still readable at the thumbnail's half scale. If it isn't, change the header, not the All components page.

## 8. Regenerate the Forge Design skill

`src/content/components/` feeds the plugin's `forge-design` skill (see `docs/CLAUDE.md`):

1. `pnpm --filter forge-docs build:forge-skill` and commit the changes under `plugin/skills/forge-design/`.
2. Add a changeset for `@tylertech/forge-plugin` (`minor` for a new component page, `patch` for wording fixes) by writing `.changeset/<slug>.md` directly.
3. `pnpm --filter forge-docs check:forge-skill` until it's clean apart from PENDING block IDs from step 1.

## 9. Verify

- `pnpm --filter forge-docs build` succeeds.
- `npx astro check` in `docs/` adds no new errors.
- Don't start the dev server (see `docs/CLAUDE.md`). Ask the user to check the usage, API, Playground and Accessibility tabs, and the card on the All components page.

## Done when

- [ ] Blocks exist for every story (merged and deployed, or PENDING with matching headings)
- [ ] Frontmatter complete and valid
- [ ] `header.astro` exists and is rendered as `<Header />` (no inline `<ComponentHeader>`)
- [ ] Overview, Usage, Rules, Basic usage, and one section per variant
- [ ] Anatomy diagram, if the component has named slots
- [ ] `accessibility.mdx`
- [ ] Components and icons registered
- [ ] API and Playground tabs populated
- [ ] All components page card shows the header thumbnail
- [ ] Forge Design skill regenerated and changeset added
- [ ] Build and type check pass

Wersje

W bazie nie ma innych skilli o nazwie component-docs-page.

Migawka bazy z 13.11.2026 · wersja paczki c47dd2218784 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100component-docs-header
    Dodaje lub zmienia nagłówek z żywym demo na stronie użycia komponentu w katalogu docs.
  • 100docs-anatomy-diagram
    Dodaje do strony dokumentacji numerowany diagram anatomii z oznaczeniami części komponentu lub układu, korzystając z AnatomyDemo i AnatomyMarker.
  • 100wideset-component-docs
    Pisze przykłady i pełną stronę dokumentacji komponentu w Storybooku i na stronie systemu projektowego.
  • 100authoring-docs
    Pisze i skraca strony serwisu dokumentacji w MDX, w tym porządki w starych stronach i nowe integracje.
  • 100acp-feature-add
    Prowadzi przez dodanie nowej funkcji, API, endpointu lub komponentu: plan przed kodem, zakres poza celem i weryfikacja nowego zachowania od początku do końca.
  • 100web-page
    Tworzy szkielet nowej strony, trasy lub sekcji panelu w aplikacji Lumen Next.js.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.