preact-ui

Files (11)

• LICENSE
• SKILL.md
• accessibility.md · references/
• component-patterns.md · references/
• forms.md · references/
• layout.md · references/
• mvvm.md · references/
• routing.md · references/
• signals.md · references/
• state.md · references/
• testing.md · references/

SKILL.md (first lines)

# Preact UI Skill

Use this skill when building Preact pages, component systems, or full applications.
Prefer the **MVVM (Model–View–ViewModel)** pattern to cleanly separate business logic from rendering.

## Architecture: MVVM in Preact

Organize code into three layers:

- **Model** — pure TypeScript modules for domain data, validation rules, and API contracts. No Preact imports.
- **ViewModel** — custom hooks (`useXxxViewModel`) or module-level signals that hold state, computed values, and commands. Bridges Models to Views.
- **View** — functional components that only render and call ViewModel hooks. No business logic inside.

Directory layout:

```
src/
  models/          # domain types, validation, factories
  viewmodels/      # useXxxViewModel hooks, signal stores
  components/      # shared presentational UI atoms/molecules
  features/        # feature slices (view + viewmodel colocated)
  routes/          # route-level page components
  services/        # API clients, storage adapters
  hooks/           # generic reusable hooks
  styles/          # global SCSS, tokens, mixins
```

## Core approach

1. Define the Model first — data shape, validation, and invariants.
2. Build the ViewModel — expose signals, computed values, and actions.
3. Build the View last — render only, bind to the ViewModel.
4. Keep components small and composable.
5. Treat accessibility and responsiveness as design constraints, not afterthoughts.

## Preact fundamentals

- Import from `preact` and `preact/hooks`, not React.
- Use `@preact/signals` for reactive state — prefer over `useState` for shared or performance-sensitive state.
- Use `preact/compat` only when consuming React-targeting third-party libraries.
- Use `preact-iso` (the official meta-framework router) or `preact-router` for client-side routing.
- Scaffold new projects with `npm create preact@latest` — it sets up Vite, TypeScript, and preact-iso.

## Signals (preferred state primitive)

- `signal(value)` — reactive value; read `.value`, write `.value =`.
- `computed(() => expr)` — derived signal; recalculates only when dependencies change.
- `effect(() => sideEffect)` — runs when dependencies change; call the returned cleanup to dispose.
- `useSignal(value)` — component-scoped signal; behaves like `useState` but with signal semantics.
- `useComputed(() => expr)` — component-scoped computed signal.
- Pass signals directly into JSX: `<span>{count}</span>` updates the DOM node without re-rendering the component.
- Define shared signals in a ViewModel module; import them in View components.
- Use `batch(() => { ... })` to group multiple signal updates into a single render.

## Hooks and state

- Use `useState` / `useSignal` for purely local UI state (toggle, hover, open).
- Use `useEffect` for external subscriptions, timers, and DOM side-effects; always return cleanup.
- Use `useRef` for DOM references and mutable values that should not trigger re-renders.
- Use `useMemo` / `useComputed` for expensive derived computations.
- Use `useCallback` only when passing stable references to memoized children.
- Avoid `useEffect` for data that can be modelled as derived/computed state.

## Workflow

1. Identify the page role:
   - marketing / landing page
   - dashboard with live data
   - form flow (wizard, multi-step)
   - content / article page
   - interactive tool or widget
2. Define the layout hierarchy before writing any component code.
3. Separate presentational and data-fetching concerns.
4. Model state intentionally:
   - local signal/state for local UI
   - module-level signals for cross-component shared state
   - `computed` for derived values — never duplicate state
5. Wire routing at the route layer; keep route components thin.
6. Integrate SCSS through predictable class names and component-scoped partials.
7. Add accessibility checks for keyboard, labels, focus order, and semantics.
8. Write tests for user-visible behavior, not implementation details.

## Component rules

- One main concern per component.
- Props describe intent, not DOM mechanics.
- Use semantic HTML first; add ARIA only when semantics are insufficient.
- Avoid overusing Context when signals or props are simpler.
- Never put business logic inside a View component — move it to the ViewModel.
- Memoize with `memo()` only when profiling identifies a bottleneck.

## Professional component patterns

### Splitting heuristics
Split a component when it has more than one independently testable concern, when its sub-trees could change independently, or when it is reused across features.

### TypeScript props
- Define explicit interfaces — never use `any` or untyped prop objects.
- Extend `Preact.JSX.InputHTMLAttributes<HTMLElement>` for low-level wrappers.
- Use union types for `variant`, `size`, and similar constrained props.

### Compound components
Group tightly related sub-components (e.g. `Tabs.Tab`, `Tabs.Panel`) under a shared namespace and use a private Context to coordinate state between them. Exposes a clean API without props drilling.

### Render props / children as function
Pass `renderItem: (item: T) => ComponentChildren` when the parent owns list/async behavior but the consumer controls individual rendering.

### Error boundaries
Wrap every route and major feature in a class-based `ErrorBoundary`. Place them at feature seams, not around individual atoms.

### Context API
Use only for cross-cutting concerns: auth user, locale, theme, feature flags. Do **not** use Context for feature data flow — signals and props are simpler and more efficient.

### Portals
Use `createPortal` from `preact/compat` for modals, tooltips, and dropdowns that must escape overflow or z-index stacking contexts.

### Controlled vs uncontrolled inputs
Prefer controlled (signal-bound) for validated forms; prefer uncontrolled (`useRef` + `FormData`) for simple, low-interactivity forms.

From prachwal-archive/web-ui-skills, MIT.

More from prachwal-archive/web-ui-skills