This entire product site is authored, validated, and rendered with Sights.See how it works
Menu

Guarded extensibility

Custom should mean site-owned—not undocumented.

A real site sometimes needs a pattern the shared catalog should not own. Sights lets trusted code add that capability while preserving the same validation, documentation, review, accessibility, and runtime boundaries.

Open the live calculator proof
A shared Sights contract flowing into a site-owned mortgage calculator with the same validation, catalog, and audit rules

Same quality contract

A custom component must bring its paperwork.

Registration happens in trusted TypeScript configuration. Declarative page content can select the component by name and supply validated props, but cannot define its code or runtime.

  • Strict props schema

    Define exactly what content the component accepts, including ranges, enums, required fields, and unknown-field rejection.

  • Intent guidance

    Document the job it solves, when to use it, when another pattern is better, and its accessibility requirements.

  • Semantic thumbnail

    Select a shared structural preset so the generated catalog communicates the pattern without maintained screenshots.

  • Validated examples

    Supply at least one working example that automatically joins the internal component viewer.

  • Runtime declaration

    State whether the component is static, uses shared motion, or loads one root-relative site-owned client module.

  • Trusted renderer

    Keep Astro implementation, structural CSS, and any client code in the consumer repository that owns the capability.

Implemented proof

The mortgage calculator is a first-class catalog component.

This consumer registers a branded educational calculator with a TypeBox schema, Astro renderer, component manifest, generated schema and docs, catalog thumbnail, browser coverage, and one isolated client module.

The server-rendered estimate remains useful before JavaScript loads. Changes are announced through a polite live region, assumptions stay visible, and no visitor data leaves the browser.

Loads the custom runtime
1 route
Load it accidentally
0 routes
Total catalog entries with the proof
25
Try the calculator example
A mortgage calculator with structured inputs and a live monthly payment result

Trusted implementation

Add the smallest complete capability.

  1. Prove the need

    Confirm that an existing component, page pattern, or template cannot express the required user outcome.

  2. Define the data boundary

    Create a strict schema that accepts meaning and settings without exposing CSS, code, arbitrary URLs, or secret names.

  3. Build from shared foundations

    Use semantic theme tokens, trusted layout primitives, responsive image policy, and native HTML behavior where they fit.

  4. Declare capabilities

    Name the client runtime, accessibility requirements, examples, thumbnail, and any future server dependency explicitly.

  5. Register and verify

    Let Sights generate the schema and catalog, render the example, audit runtime isolation, and run the consumer browser gate.

Extension questions

Where custom behavior belongs.

Can a custom component accept raw HTML or class names?

It should not. Site-owned components use the same content safety policy as built-ins. Differences become typed semantic fields; implementation details stay in trusted code.

Does every custom component need JavaScript?

No. Static Astro renderers are preferred. A client module is appropriate only when browser state or interaction materially improves the outcome.

Can a site use React?

The architecture allows framework components as trusted implementation details. Static components should render without hydration; interactive islands should hydrate only the owning component.

When should a custom component move into Sights?

After more than one real consumer proves the same responsibility, prop vocabulary, responsive behavior, accessibility contract, and review need.

See the boundary working

Use the custom calculator, then inspect an ordinary page.

The calculator route loads its declared module. The rest of the product site does not. That small fact is the static-first architecture made visible.

Open the interactive example