Read the Standard

A Project's Selection#

Your project does not adopt all of LiteSpec. It makes four choices in .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 Claimwick example in examples/claimwick/ 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/.

The project file holds more than the selection: paths points at the documentation roots, refusals names the codes the two derived generic results carry, and reviewedLiteSpecVersion records the release the team pinned, 4.0.0. The project file page lists every field.

The Page Arrangement#

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
    mobile/                     native mobile apps
      android/                  Android apps
  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.

Page Sections and Provisions#

A standards page carries the same sections every time:

• Intent introduces what the page covers, who applies it, and why it matters.
• 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.

Each rule is a heading followed by its ID line. Here is one from the domain page:

### Keep Domain Independent of Outer Layers

**ID:** `litespec/backend/domain#keep-domain-independent-of-outer-layers`

**Strength:** rule

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

**Rationale:** Domain that references only the language standard library and its own types compiles and tests with no infrastructure at all.

**Reviewed for:** Domain code references the language standard library and project-owned Domain types, with no outer-layer reference.

Its ID line states litespec/backend/domain#keep-domain-independent-of-outer-layers: the page path, then the heading. Its Strength line states how binding it is: rule binds every project it applies to, default binds unless the project records its own choice, and advice is experience to apply with judgement. The Statement 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.

Each page also states the scope its provisions apply to: the technology, the part of the system, and the kind of thing made. A provision narrower than its page names its scope, so an agent editing one file can ask which provisions govern it. The last line of each rule is its verification: **Checked by:** names the command that checks it, or **Reviewed for:** asks the question a reviewer answers. That shows whether a tool or a person catches a slip.

Departures from the Rules#

The standard expects departures and gives each one a home:

• An exception record of kind departure replaces one provision for your project, naming the records it sets aside with its reason and an expiry date. An agent follows your exception over the standard.
• A project convention is a default you replace by stating your own in the provision shape, under .litespec/governance/conventions/.
• An exception record of kind gap records a check that stays red until you fix it, with its reason and an expiry date, so the check does not 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 or convention, then a selected extension, then the deeper page, then the shallower one. litespec rules <path> applies that order and shows the replacement in place of the original.

The Claimwick example carries one exception, at examples/claimwick/.litespec/governance/exceptions/export-review-bypass.yaml:

type: exception
id: exception/export-review-bypass
title: Export Review Bypass
kind: departure
covers: litespec/backend/application#enforce-target-authorization-in-the-pipeline
subject:
  - use-case/spending.export-expenses
reason: The weekend export runs with no reviewer on shift.
consequences: Weekend exports run without a second pair of eyes until a reviewer returns.
expiresOn: 2027-01-01

Read it as one departure: it names the provision it replaces in covers, the records it sets aside, the reason, the consequences, and the expiry date. 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 on the pattern's page, so you can choose by looking.

Next#

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