Read the Standard

Intent#

This page explains how the standard is organized, so you can find the rules that apply to your project and read a rule the way it's meant.

A project's selection#

You don't adopt all of LiteSpec. Your project makes four choices in its litespec.project.json, and those choices decide which pages apply:

litespec init --preset dotnet-react --size small writes a first project file with a common selection. The selection page on the site does the same in a form and shows which pages apply.

The library example the model builder tests use declares its own selection in litespec.project.json:

{
  "size": "large",
  "shape": "server",
  "stacks": ["dotnet", "svelte"],
  "selectedExtensions": []
}

Read it as four answers: size large, shape server, the dotnet and svelte stacks, and no extensions. That selection applies backend/dotnet/ and frontend/web/svelte/, and it does not apply frontend/web/react/ or frontend/blazor/.

How the pages are arranged#

The folder a page sits in decides who applies it:

docs/
  core/  workspace/  quality/   every project
  backend/                      every project with a backend
    dotnet/                     projects that select the dotnet stack
  frontend/                     every project with a frontend
    patterns/                   UI patterns, for every frontend
    web/                        React and Svelte frontends
      react/  svelte/           each web stack
    blazor/                     Blazor frontends
  ext/                          only the extensions a project selects

Selecting a stack applies its folder and every folder above it. A React project applies frontend/, frontend/web/, and frontend/web/react/. The upper pages state the principle, such as "pages compose shared components only". The lower pages state how one stack does it, such as which React component library and which test runner.

The diagram below shows which folders a server project with the dotnet and react stacks applies, and which it does not.

The other folders explain rather than govern: learn/ (these pages), tutorial/, guide/, reference/, and tools/, which describes each command.

Reading a page#

A standards page has the same sections every time:

• Intent says what the page covers.
• Concepts, when present, explain the ideas the rules use.
• Standards are the rules you must follow.
• Conventions are defaults you may replace with your own.
• Verification says, for each rule, how it's checked.

Each rule is a heading, and the heading is also its ID. Here is one from the domain page:

### Keep Domain independent of outer layers

**Requirement:** The Domain code MUST reference only the language standard library and project-owned Domain types.

**Rationale:** No persistence, web, mediator, logging, configuration, injection, serialization, or provider package enters Domain. Infrastructure registers a persisted discriminator rather than Domain carrying a serialization attribute.

Its ID is litespec/backend/domain#keep-domain-independent-of-outer-layers: the page path, then the heading. The Requirement is the rule itself, one sentence with one capitalized word that sets its strength, as in internet standards: MUST, MUST NOT, SHOULD, SHOULD NOT or MAY. Everything under Rationale and Example explains it and adds no obligation.

In the Verification table, each rule is marked checkable, with the command that checks it, or guidance, with the question a reviewer asks. That tells you whether a tool or a person catches a slip.

When a rule doesn't fit#

The standard expects departures and gives each one a home:

• An Exception record replaces one Standard for your project, with its reason, an owner, and a date to review it. An agent follows your exception over the standard.
• A replaced Convention is a default you change by stating your own in your project's documentation.
• A Known gap records a problem you accept for now, with an owner and an end date, so a check doesn't fail on it forever.
• An extension can replace a baseline rule when you select it. The EF Core extension, for example, replaces the default persistence rules with its own.

When guidance overlaps, the most specific source wins: your exception, then a selected extension, then the deeper page, then the shallower one.

The library example carries one exception, at docs/exceptions/shelf-check-bypass.md:

{
  "type": "exception",
  "id": "exception/shelf-check-bypass",
  "standard": "standard/lending.quiet-shelf-check",
  "reason": "The import runs before opening.",
  "reviewBy": "2027-01-01"
}

Read it as one departure: it names the standard it replaces, the reason, and the date to review it. An agent follows the exception over the standard until that date.

UI patterns#

The pages in frontend/patterns/ work differently. Each one covers a group of recurring interface questions, such as how a record's page header is laid out or how a list filters. Every pattern offers several options, each drawn as a wireframe, and names a default. Your project keeps a catalog of the option it chose for each pattern. The site draws every option, and litespec patterns preview draws them locally, so you can choose by looking.

Next#

Records and the project model explains what your project writes down.