Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Pisanie

documentation

/documentation

Czyta, aktualizuje i tworzy dokumentację komponentów systemu designu w Sanity oraz na stronie dokumentacji, w tym opisy komponentów.

Repozytorium
design-system ↗
Licencja
AGPL-3.0
Ostatnia zmiana repozytorium
26.10.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
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

Co robi i kiedy

Czyta, aktualizuje i tworzy dokumentację komponentów systemu designu w Sanity oraz na stronie dokumentacji, w tym opisy komponentów.

Oryginalny opis (EN)

Use when reading, updating, or creating documentation for design system components. Triggers on tasks involving Sanity content, component docs, documentation pages, or the documentation website. Use this skill whenever the user mentions docs, component documentation, Sanity content, the documentation website, or wants to update descriptions for components in the design system.

Jak działa

  1. 1. Sanity CMS — component docs and articles
  2. 2. Local MDX files — design guides and identity pages
  3. How the website works
  4. Working with Sanity
  5. Writing Norwegian docs
  6. Common tasks
Sekcje z nagłówków SKILL.md, w oryginale · 141 linii, 995 słów
Podgląd SKILL.md
---
name: documentation
description: Use when reading, updating, or creating documentation for design system components. Triggers on tasks involving Sanity content, component docs, documentation pages, or the documentation website. Use this skill whenever the user mentions docs, component documentation, Sanity content, the documentation website, or wants to update descriptions for components in the design system.
---

# Documentation Skill

Documentation in the Entur Design System lives in **two places**:

## 1. Sanity CMS — component docs and articles

- **MCP server:** `Sanity` (tools are prefixed `mcp__Sanity__*`)
- **Project ID:** `npa0lfls` | **Dataset:** `production`
- **Studio app:** `apps/studio-linje/`
- **Document types:** `componentDoc` (component docs with tabs) and `page` (articles)

All Sanity tools are deferred. Load each via ToolSearch before first use:

```
ToolSearch: select:mcp__Sanity__query_documents
ToolSearch: select:mcp__Sanity__patch_documents
ToolSearch: select:mcp__Sanity__publish_documents
```

If the MCP server is disconnected, ask the user to reconnect via `/mcp`.

Always pass `resource` on every call:

```json
{ "resource": { "projectId": "npa0lfls", "dataset": "production" } }
```

## 2. Local MDX files — design guides and identity pages

- **Location:** `apps/documentation/src/pages/` (file-based Gatsby routing)
- **Format:** MDX with frontmatter (`title`, `description`, `route`, `menu`, `order`)
- These are **not** in Sanity. Edit them directly.

## How the website works

The docs site (`apps/documentation/`) is a Gatsby 5 app:

- Sanity content pulled at build time via `gatsby-source-sanity`
- MDX files processed via `gatsby-plugin-mdx`
- Portable text rendered with custom resolvers in `PortableText.tsx`
- Templates: `ComponentDocTemplate.tsx` (componentDoc) and `ContentTemplate.tsx` (page)
- Search is a local flexsearch index built in `gatsby-config.ts`. A componentDoc's body text
  reaches it through `_rawIntro` and `_rawTabs` in the normaliser there — a new content field
  is not searchable until it is added to that query and serialised into `sanityContent`.

## Working with Sanity

Read [references/component-doc-standard.md](references/component-doc-standard.md) **first**
for what to write and where — the standard tabs, standard section titles per tab, writing
principles, and how to migrate a tab from legacy `content` to the current `sections` model.
The files below cover mechanics only, not what "correct" documentation looks like.

Read [references/sanity-querying.md](references/sanity-querying.md) for GROQ patterns, strategic querying, and drafts handling.

Read [references/sanity-patching.md](references/sanity-patching.md) for how to update documents — critical rules for `set`, `insert`, `unset`, portable text structure, `_key` generation, publishing, and error handling.

Read [references/sanity-schema.md](references/sanity-schema.md) for document structure, schema types, and the componentDoc tree.

## Writing Norwegian docs

All documentation prose is Bokmål, never Nynorsk.

**Do not translate technical terms.** Keep the English word when it is:

- the name of a prop, function, keyword, type, HTML element, or CSS feature — `children`, `ref`, `disabled`, `useEffect`, `aria-live`, `role="status"`, `cascade layer`
- a framework or platform concept a Norwegian developer would say in English anyway — `parent`, `state`, `hook`, `callback`, `default`, `token`, `wrapper`, `live region`

Translate only ordinary words: component → komponent, page → side, button → knapp, width → bredde.

Inflect around the English term rather than Norwegianising it: `props`-ene, `prop`-en, `children`-en, `items`-prop-en. Never `proppene`, and never invent a Norwegian noun for something the API calls something else — the reader has to map the word back to the code.

Rule of thumb: if a Norwegian developer would say the English word out loud, keep the English word.

Other prose rules:

- No literally translated English idioms. Describe the goal plainly instead.
- Prefer a comma or full stop over a dash when joining clauses. When a dash is right, use an en-dash (–), never an em-dash.
- Keep it generic — never bake one team's component or domain names into the docs.
- Refer to a component by its own name with a Norwegian ending — `Tag`-en, `Modal`-en. Never
  translate the name into an ordinary Norwegian noun ("merket", "vinduet"): the reader has to
  be able to map the word back to the component they import.
- Prefer "bør" over "skal" for guidance. Reserve "skal"/"må" for what is actually required,
  such as an accessibility obligation.

## Common tasks

### Write or update a component doc section

1. Read [references/component-doc-standard.md](references/component-doc-standard.md) to
   decide which tab and section title the content belongs to.
2. Query the `componentDoc` by title in Sanity; get the tab's current `sections` (see
   querying reference) so you know whether the target section already exists.
3. Write content using the standard's guidance on which block type to use (prose vs. list vs.
   `guideline` vs. `codeExample` vs. `propsTable`).
4. Patch with `insert` (new section) or `set` (editing an existing block) — see patching
   reference.
5. Tell the user changes are saved as draft; confirm before publishing.

### Replace an MDX page with a Sanity doc

Some components still have a page under `apps/documentation/src/pages/komponenter/`. The
Sanity doc and the MDX file resolve to the same route, so the two have to change together:

1. Build the Sanity doc while the MDX page is still live — a draft changes nothing publicly.
2. Delete the MDX file in the same branch as the rest of the work, in its own commit.
3. Publishing the Sanity doc and merging that deletion are two separate releases. Say which
   one is happening first: until both are done the route is either duplicated or missing.
4. Check what the MDX frontmatter carried that Sanity has no field for (`tags`, custom
   `menu`/`order`) before deleting it.

### Migrate a tab from legacy `content` to `sections`

Follow the step-by-step migration procedure in
[references/component-doc-standard.md](references/component-doc-standard.md#migrating-a-tab-from-legacy-content-to-sections).
Leave `content` in place until every section from it has been moved; confirm with the user
before publishing.

### Update component docs after a release

1. `git log` between release commits — focus on `feat` and `fix` for consumer-facing changes
2. Query the `componentDoc` by title in Sanity
3. Get the tab's `sections` with `_key` values (see querying reference) — or `content.items`
   if the tab isn't migrated yet
4. Get full block structures for blocks to modify
5. Patch with updated text (see patching reference)
6. Tell user changes are saved as draft; confirm before publishing

### Add a new section

1. Read the standard ([component-doc-standard.md](references/component-doc-standard.md)) to
   pick the right section title for the content
2. `setIfMissing` the tab's `sections` array if it doesn't exist yet
3. `insert` a new `docSection` (`{_key, title, items}`) with unique `_key` values (random 12-char hex)

### Fix duplicate or broken content

1. Query the full `sections` (or legacy `content.items`) for the affected tab
2. Filter out duplicates or fix broken blocks
3. `set` the entire array with the corrected version
Pliki w paczce (5)
  • SKILL.md 7 KB
  • references/component-doc-standard.md 13 KB
  • references/sanity-patching.md 4 KB
  • references/sanity-querying.md 3 KB
  • references/sanity-schema.md 7 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · entur/design-system100AGPL-3.0
software-combined/SC_AI100Apache-2.0
DaveSkender/Stock.Indicators100Apache-2.0
mcouthon/agents100MIT
YLfjuk/deltafold100MIT
comet-ml/opik100Apache-2.0
runwield/runwield100MIT
anthropics/knowledge-work-plugins100Apache-2.0
luocfprime/labtasker100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 559f66dfbfaa (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-documentation
    Czyta zestaw komponentów systemu projektowego w Figmie i zapisuje ramkę dokumentacji obok komponentu: anatomia, właściwości, stany, użycie i dostępność.
  • 100dh-component-docs
    Pisze dokumentację jednego komponentu na podstawie kodu, stories i realnych miejsc użycia, w tym stanów i zasad użycia.
  • 100design-system-architecture
    Buduje skalowalne design systemy z tokenami, API komponentów i dokumentacją, przy tworzeniu lub rozwijaniu bibliotek komponentów.
  • 100component-docs
    Pisze wpis dokumentacji jednego komponentu na podstawie jego kodu, stories i rzeczywistych użyć: stany, zasady użycia i dostępność.
  • 100repo-website-api-create
    Tworzy strony dokumentacji API dla nowych funkcji, typów i komponentów Formisch, które jeszcze nie mają opisu na stronie.
  • 100update-docs
    Aktualizuje publiczną dokumentację w katalogu docs/public, gdy zmieniają się funkcje albo narzędzia w projekcie.

Uwagi i zgłoszenia

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