Project policies

Tilo’s standing rules for contributors, human or agent, in one place. Each rule says why it exists and how it is held:

• Check: a hook or CI step fails when the rule is broken. The path names the check; reading it is the precise definition of the rule.
• Review: nothing automated holds it yet. Reviewers and authors carry it, and a change that breaks it is fixed forward when noticed.

Where a rule is described in more depth elsewhere (AGENTS.md, CONTRIBUTING.md, HIG.md, the security model), this page links there instead of repeating it. A rule listed here as a check and described differently elsewhere is defined by the check.

Most checks run in two places: .githooks/pre-commit and .githooks/commit-msg locally (enable them with python3 tools/dev/install-git-hooks.py), and CI (.forgejo/workflows/), which runs the policy suite tools/policy/run.sh, the diff-based gates, formatting, cargo deny, Clippy and the tests.

Exceptions

An exception is a reviewed change to the rule’s own exception list, made in the change that needs it, with the reason written next to the entry:

Changing a rule itself is a change that edits this page and the check together.

Process

Code review: Draft, decision needed

Review is optional and informational today: requests, approvals and change requests never affect whether a change lands. A review policy (what needs a second reader, and who) is still to be decided; until then nothing on this page depends on review having happened.

Repository hygiene

Rust code

tilolang sources

Architecture boundaries

Each of these keeps one subsystem’s internals behind its API, so the subsystem can change without editing its callers.

Dependencies and runtime

UI and apps

The product reasoning behind these is in AGENTS.md (“Project Scope”) and the HIG.

| Rule | Enforced by | | ———————————————————————————————————————————————————————————————————————————————————————————————————————————– | —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————– | –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– | | Every capability is an action on a resource: what a click can do, a screen reader, a script and an agent can do through tilo-actions. | Partly: check_app_resource_action_contract.py (every graphical app publishes resources and actions; the APIs the resource model replaced are banned in apps and examples, resources.md §8; controls an app activates through a private closure (on_click, on_change, on_select, …) instead of an action, and the closure-run buttons of toolkit composites (row, property and card actions; dialog footers and menu entries are published as their dialog’s and menu’s controls), are counted per app in production code against baselines that only fall; a callback that submits a published action through the dispatcher runs the shared route and is not counted) and check_atspi_endpoint_contract.py (every app uses the production AT-SPI endpoint). That a given feature has its action is review. | | Colours, spacing, radii and type come from the Theme; nothing is hard-coded. | Check: the ratchets in crates/sdk/ui-core/tests/ (design_token_audit.rs, spacing_token_audit.rs, typography_token_audit.rs; HIG §9.13) | | User-visible strings are Fluent keys, and every key a crate uses exists in each catalogue it ships. | Check: check_app_copy.py; copy style ratchet copy_audit.rs. That no literal reaches the screen is review. | | Copy says state, outcome or next step in the person’s words: no narration, implementation words, machine ids, {:?} output, all caps, facts joined with a separator glyph (“·”, “•”, “ | “, dashes, “ / “) or unicode symbols as icons; buttons named by outcome; one name per thing (HIG §4). | Check: check_copy_language.py over every catalogue, with the glossary copy_glossary.toml and a shrink-only per-catalogue baseline; tilo_copy_lint rejects {:?} handed to a copy builder. | | Shell and app surfaces are built from the design system’s primitives: no hand-painted button, row or chip shapes, no separator-glyph joins or symbol icons in string literals a person reads (an agent’s tool schemas and summaries are model text, not interface), no raw colour literals (docs/design-language.md, “Primitives”). A session surface (a sheet, menu, quick-settings page, bar, banner, lock screen, onboarding page) is composed from the shared components like an app’s view: it paints no panel, edge or shadow of its own, no bare text run, no row, no written-out radius, padding or gap, keeps no scroll position itself, and wraps nothing in a decorator that paints it (ui-inventory.md). | Check: check_primitives.py over production Rust in crates/session/ and apps/ (the session-surface rules are counted in crates/session/ except the compositor, which shapes a client’s buffer), with a shrink-only per-file count baseline primitives_baseline.txt. | | Session copy says Workspace, People, Collaborator, Participant, not room or peer. | Check: check_session_copy_contract.py | | Every action declares the other words people use for it beside its title (keywords), plain words with no code or internal terms; search ranks them as it ranks titles and keeps no synonym list of its own. | Check: check_action_keywords.py for the wording; that every shell action declares some is the shell’s every_shell_action_declares_the_other_words_people_use_for_it, and the words finding their action is every_common_phrasing_finds_its_action_in_the_top_three | | Never hand-roll a text field, button, dialog or other control; extend the shared widget (HIG §8). | Review; the raw_paint ratchet catches painting outside widgets | | Search, undo, history, device sync and theming are system services. Apps register search providers and never draw a search field (HIG §4a). | Review | | The OS owns window chrome: apps draw no title bar. Windows never overlap or float. | Review | | Apps start empty: no seeded data on the live path; sample data only behind --shots or a demo flag. | Review | | Apps hold no platform code and declare every capability their code uses. | Check: check_app_capabilities.py, tilo-app check --lint --all in lint.yml (platform code against a shrink-only baseline) | | UX dictates the code: a change starts from what the person sees and does. | Review | | Input and accessibility parity: keyboard, pointer, touch and assistive technology all reach every function; layouts survive enlarged text, high contrast and small displays; looking good does not need an expensive GPU. | Review; check light, dark and high-contrast shots (TILO_SHOTS_THEME) | | Durable user state is never lost silently: formats stay readable across versions, and a failed write or migration is reported and recoverable. | Review |

Motion

Motion follows the input. Direct manipulation (drag, swipe, pinch) animates continuously and hands its velocity to the settle. A pointer click may animate at fast or base. A keyboard shortcut applies its result on the next frame; only spatial context may move, at fast at most: Super+→ shows the focused window at once and slides the viewport only when the target was off screen, Ctrl+Tab has no crossfade, and the workspace switch keeps a fast direction cue. Repeated presses never queue. Agents and scripts follow the keyboard rule. Reduced motion stays the global override.

A shortcut is a frequent expert action with a known result, so animating it adds latency to every repetition, while pointer and finger motion explains where things went. Scope: the shell and every toolkit widget it lays out. Transitions carry their source (ui::tokens::MotionSource) from where the operation runs, and tokens.motion picks the duration per source; the specification is window-management.md § Motion with the durations in HIG §9.7.

Animations are composed from the motion library. Every animation in the toolkit, the shell and the apps uses a named motion from ui::motion (HIG §9.7), which decides its spring, its duration, its reduced-motion variant and what a shortcut gets; a motion that is genuinely new goes into the library. Check: check_motion_library.py fails on easing math, ad-hoc springs (a SpringSpec built by hand included), lerp-over-time (a span of time divided by a constant included) and literal motion timings (a spring timed by the call site’s own duration, a duration constant named for a fade or a slide, a literal duration handed to a motion helper) outside the library; content curves (video keyframes, paint physics) are its short exception list.

Check: the_first_frame_after_a_chord_shows_the_final_layout in crates/session/desktop/tests/navigation.rs (the first frame after a chord or action shows the final layout, and only the viewport may still move, within fast). A new transition that ignores its source is review.

Security and sandboxing

The sandbox is the security boundary that makes uninstalled apps safe; never weaken it for convenience (security model).

Testing and verification

Legal and interoperability

Candidates for automation

Review-only rules above that look cheap to check, not yet done:

• Motion: a ratchet for literal animation durations (the tab bar, spawn fade and strip indicators still carry their own constants).