TypeScript Style Guide

This skill owns TypeScript policy within the kit. Apply the relevant conventions and their stated exceptions to the current task.

Use the repository's existing tools for enforceable rules. Do not reimplement deterministic TypeScript, ESLint, or formatting checks.

Workflow

1. Establish policy. Inspect the consuming repository's instructions and configuration. Explicit repository conventions take precedence; use this guide where the repository is silent.
2. Load the applicable rules. Read the references for the decisions the task substantively touches, following links to related rules. Finish when each relevant decision has a rule source.
3. Apply the rules. Make or review the requested change using those conventions. Adapt examples to the application and lint fragments to the existing configuration.
4. Verify. Use the shortest feedback loop that exercises the affected behaviour: focused type checks, lint, formatting, and behavioral tests as relevant. Expand by impact and run repository-mandated gates at their defined stages. Review the remaining conventions directly. Finish when each relevant rule is satisfied or a justified exception is identified. Report the checks and decisions.

References

Choose the decisions the task touches. Long references provide section-level contents; examples retain their assumptions and trade-offs.

Conventions

• Types — read for inference, readonly data, constants, template literal types, any/unknown, assertions, type errors, type definitions, arrays, type imports, and generated service types. Owns narrowing and assertion policy, including runtime null checks.
• Discriminated unions — read for mutually exclusive states, variant-specific required properties, exhaustive narrowing, function arguments, and React props. Owns these decisions when they involve discriminated unions.
• Functions — read for responsibility, statelessness, purity, side effects, argument design, and public return contracts.
• Variables and absence — read for constants, literal-union state, enum alternatives, and the meaning of null versus undefined; Types owns runtime narrowing.
• Naming and documentation — read for named exports, generic parameters, React names, comments, and TSDoc.
• Source organization — read for collocation, feature ownership, import paths, and frontend/backend structure; Types owns type-only imports.
• React APIs and data flow — read for components and hooks, props-to-state, component roles, state placement, and compound components.
• Tests — read for behavioral test design, Arrange–Act–Assert, isolation, mocking, test names, and snapshot selection.

Worked comparisons

• State modeling — read when comparing success/error payloads, exhaustive narrowing, and query-state designs (02, 07, 08).
• Responsibilities and capabilities — read when comparing typed dependencies, platform boundaries, and type collocation (10, 13, 14, 15).
• Trust and validation boundaries — read when comparing trusted JSON, typed setters, runtime schemas, and HTTP responses (01, 05, 06, 09); apply the Types policy above.
• Inference — read when deriving keys, preserving keyed returns, or registering schema-handler pairs (03, 04, 16).
• Concurrency and execution — read when bounding work or assigning middleware invariant ownership (11, 12).