Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

interface-design

/interface-design

Podaje zasady projektowania interfejsów API pakietów: gdzie konfiguracja, zachowanie i stan należą w warstwach schematu, endpointu i hooka, przy zmianach opcji w packages/*.

Repozytorium
data-client ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.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

Podaje zasady projektowania interfejsów API pakietów: gdzie konfiguracja, zachowanie i stan należą w warstwach schematu, endpointu i hooka, przy zmianach opcji w packages/*.

Oryginalny opis (EN)

Interface design principles for package APIs — where configuration, behavior, and state belong across schema, endpoint, and hook layers. Use when adding or changing options, behavior, or state in packages/*.

Jak działa

  1. The Three Layers
  2. Placement Principles
  3. Declarative Over Imperative
  4. What Stays the Same vs. What Varies
  5. Anti-patterns
Sekcje z nagłówków SKILL.md, w oryginale · 51 linii, 551 słów
Podgląd SKILL.md
---
name: interface-design
description: Interface design principles for package APIs — where configuration, behavior, and state belong across schema, endpoint, and hook layers. Use when adding or changing options, behavior, or state in packages/*.
---
# Interface Design

[Resources](/rest/api/resource) are a collection of **methods** for a given **data model**. [Entities](/rest/api/Entity) and [Schemas](/rest/api/schema) declaratively define the data model. [Endpoints](/rest/api/Endpoint) are the methods on that data. Both should be as **declarative as possible** — describing *what*, not *how*.

These concerns separate into three layers. Each changes for different reasons, is used in different contexts, and composes independently. Place new configuration or behavior in the layer whose **reason to change** matches.

## The Three Layers

| Layer | Declares… | Changes when… | Examples |
|-------|-----------|---------------|----------|
| **Schema** (Entity, Collection, Query) | Data model and relationships | Data shape or identity changes | `pk()`, `schema`, `merge()`, `process()`, `indexes` |
| **Endpoint** (Endpoint, RestEndpoint, resource) | Methods on that data | API contract or cache policy changes | `path`, `method`, `schema`, `pollFrequency`, `getOptimisticResponse()` |
| **Hook / Composable** (useSuspense, useDLE, useQuery) | Data dependencies at point of use | UI interaction pattern changes | Suspense, `{ data, loading, error }`, subscription lifecycle |

## Placement Principles

**If it describes data identity or relationships** → Schema. Schemas are protocol-agnostic and UI-agnostic. An Entity's `pk()`, `merge()`, and nested `schema` work identically whether data arrives via REST, WebSocket, or `controller.set()`.

**If it describes how to obtain or mutate data** → Endpoint. Declare `path`, `method`, `schema`, and policy — not imperative fetch logic. Endpoints are UI-agnostic: the same endpoint powers React, Vue, SSR, or imperative `controller.fetch()`.

**If it describes how the user experiences data** → Hook. Loading states, error delivery, suspense, subscriptions, and reactivity adapters are UI concerns. Hooks co-locate data dependencies where data is rendered — not at the top of a tree. They are thin adapters over `Controller`, not duplicate cache logic.

**If it's shared policy** (expiry, staleness, optimistic updates) → `EndpointExtraOptions`. These live on endpoints as per-request policy, but are implemented by `Controller`/managers, not hooks.

## Declarative Over Imperative

Favor declarative configuration that the framework interprets over imperative code users must write:

- **Schemas**: Declare `pk()`, `schema` relationships, `merge()` policy — the store handles normalization.
- **Endpoints**: Declare `path`, `method`, `schema`, `optimistic` — the framework handles fetching, caching, and updates.
- **Mutations**: `ctrl.fetch(TodoResource.partialUpdate, { id }, { completed })` — a single typed statement describing the action, not manual cache updates or invalidation cascades.

## What Stays the Same vs. What Varies

The `endpoint + args` input pattern is the **stable interface** shared by all hooks and `controller.fetch`. This enables one endpoint definition to power `useSuspense`, `useDLE`, `useCache`, `useSubscription`, or imperative `controller.fetch` — without the endpoint knowing which UI pattern consumes it.

When adding a new capability, ask:
- **Does every consumer need this?** → Endpoint or schema.
- **Do only some UI patterns need this?** → Hook or hook option.
- **Does it vary per call site?** → An argument, not a property.
- **Does it vary per endpoint definition?** → A property or `extend()` override.

## Anti-patterns

- Imperative update/invalidation logic where a declarative schema or `optimistic` flag suffices
- Encoding UI concerns (loading, error display) into endpoint or schema definitions
- Encoding transport details (URL construction, headers) into hooks or components
- Duplicating store/cache logic in hooks instead of going through `Controller`
- Adding hook-specific state to `Controller` — it serves all consumers (React, Vue, imperative)
- Prop-drilling fetched data instead of co-locating `useSuspense` where data is rendered

Wersje

RepozytoriumWynikLicencja
Ta strona · reactive/data-client100Apache-2.0
zpyoung/quirk100MIT
tushaarmehtaa/tushar-skills100MIT
nttare0/all-100MIT
3xC1ibR/interface-design100MIT
dammyjay93/interface-design100MIT
Tariq-Anjum/tisserand90MIT
seikaikyo/dash-skills90MIT
hamzzaqureshi/gravidex90MIT

Migawka bazy z 13.11.2026 · wersja paczki f6dd06160f7b (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

  • 100api-and-interface-design
    Opisuje wzorce projektowania stabilnych interfejsów: endpointy REST i GraphQL, granice modułów, kontrakty typów i zmiany interfejsów publicznych.
  • 100api-and-interface-design
    Podaje wzorce stabilnych API: endpointy REST i GraphQL, granice modułów, kontrakty typów i zmiany publicznych interfejsów.
  • 100go-interface-design
    Podaje wzorce projektowania interfejsów w Go: interfejsy niejawne, definicja po stronie konsumenta, weryfikacja zgodności, kompozycja i zasada przyjmuj interfejsy, zwracaj struktury.
  • 95r-package-development
    Podaje wskazówki do tworzenia pakietów R: zależności, projekt API, testy i dokumentację.
  • 100api-and-interface-design
    Prowadzi projektowanie stabilnego API i interfejsów: granice modułów, kontrakty typów, endpointy REST lub GraphQL.
  • 100api-and-interface-design
    Projektuje granice modułów, API, klucze konfiguracji i schematy: trudne do błędnego użycia i bezpieczne przy wdrożeniu i wycofaniu.

Uwagi i zgłoszenia

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