Version 1 of 1 · · razie · in person · Current version

name
d3-f-customize
description
Customizing d2 — the topics d2 reads to decide how it looks, what it says and what it allows; which one changes what, how to edit one, how to make something new customizable. Get skills only from /api/v2/skills/d3.
feature
declared
concepts
[surface]
tags
#skill #feature #d3skill #wip

d3-f-customize

Intro

Change d2 by editing a topic, not by a build.

d2 is built with d2: its bar, its tiles, its look, its limits and much of its wording are topics d2 reads, on the project or inherited from base d2. Before any change to how d2 looks or behaves, find the topic that already decides it. Spec: Spec › declared, Spec › inherited; design: Design › declared.

Essentials

  • R-custom-1 MUST look for the topic that decides it before filing work for a builder (d3-f-design › build_asTopic).
  • R-custom-2 A customizing topic is edited like any topic: its draft, then publish; it applies when published, with no restart.
  • R-custom-3 NEVER depend on the topic being there or being right: a missing topic or a line d2 can't read falls back to d2's built-in value and is listed as a problem.
  • R-custom-4 NEVER make a topic in a project with the name of one it inherits (E_INHERITED): change it on the base that holds it, or use the project's own topic where one is read (Nav, Settings:PROJECT, Settings:Permissions).
  • R-custom-5 Base d2's topics change every project: only on your person's word, as drafts they publish.

Concepts

surface

A topic d2 reads to decide how it looks, what it says or what it allows. Also called: settings topic, config topic, customization point. Fields: the topic's name; where it is read from (the project, else the chain of bases, else built in); who may edit it; its shape (frontmatter keys, a table, a list); what happens to a bad line.

The surfaces today:

to change topic read from its own skill
the top bar, its links and menus Nav the project, else base d2, else built in d3-f-pages
the Toolbox's tiles Toolbox base d2, tiles filtered by show= d3-f-help › toolbox_addTile
the Settings page's tiles UserSettings base d2 —
the look of every page, of a built-in block Style:Base (its css block) base d2 d3-f-styles › style_editBase
a project's colours and fonts a Style: topic named in Nav's style: the project d3-f-styles › style_write
a project's base, level, who sees and edits, whether people see each other's drafts Settings:PROJECT the project d3-f-support › settings_read
what each role's AI may do without asking Settings:Permissions the project, else base d2 d3-f-permissions › table_customize
limits and prices per plan Settings:Quotas base d2, the Architect d3-f-accounts › plan_quotas
the box's warn and alert levels, self-healing, audit keeping Settings:System base d2, the Architect d3-f-ops
a view's first-visit box and its info icon the view's Help: topic, frontmatter brief: base d2 d3-f-help › help_onPage
what a new project starts with the Template: topics base d2 d3-f-pages
the new-project flow WelcomePage, WelcomeKind base d2 —
what a new AI is told first Skill:d2-start, the role skills base d2 d3-f-onboarding › startPrompt_write

Designed, not built yet (Design › declared): Settings:Messages (the words of notices and of d2's plain pages), Settings:Process (roles and statuses: label, colour, order), a label row in Settings:Quotas, the user menu's entries under {{user}} in Nav, the Footer topic (the small line under every page). Until each is released its words are in code and a change is a builder's ticket.

Never a surface: the Architect's pages, Permissions' own page, the vault, log-in and sign-up: a broken topic there could lock someone out.

surface_find

  • Summary: which topic decides it: the table, then the topic itself.
  • When: your person wants d2 to look, say or allow something different; before any ticket.
  • Needs: what should change, and on one project or on all.
  • Call: GET /api/v2/skills/d3?role=<your role>&concept=surface → the row → GET /api/v2/topics/<topic> on the project (an inherited one answers as if it were the project's, marked with where it comes from).
  • Rules: R-custom-1. One project only: the project's own topic where the row says the project. Every project: base d2's, under R-custom-5. Not in the table: it is code, or it should become a surface → surface_add.
  • Errors: E_NOT_FOUND → the project has none and inherits none: d2's built-in value is in use.
  • Gotchas: —

surface_edit

  • Summary: edit its draft, publish, look at the page it changes.
  • When: the surface exists and you may edit it.
  • Needs: the topic's current text and shape; your person's word for base d2.
  • Call: d3-f-drafts › draft_save → d3-f-drafts › publish_draft → open the page it changes and check it there.
  • Rules: R-custom-2, R-custom-3, R-custom-5. Keep the topic's shape: a table stays a table, a key stays a key. Change one thing, publish, look; a line d2 can't read is listed on the topic's own page.
  • Errors: E_INHERITED → R-custom-4 · E_SCOPE → it is the Architect's or an admin's: say so to your person.
  • Gotchas: —

surface_diagnose

  • Summary: an edit that doesn't show: wrong topic in the chain, a bad line, or still a draft.
  • When: a surface was edited and the page didn't change.
  • Needs: the topic, the project, the page.
  • Call: is it published (GET /api/v2/drafts)? → which topic answers on this project (the project's, a base's, built in)? → the problems listed on the topic's page.
  • Rules: R-custom-3. A project's own topic hides the base's for that project. /d2admin, /razadmin and /ai always draw base d2's bar. A <style> in a topic is stripped.
  • Errors: —
  • Gotchas: —

surface_add

  • Summary: make something customizable: a line in an existing surface first, a new topic last.
  • When: your person wants to change words, a label, a colour, a limit or a list that is in code today.
  • Needs: which of the four kinds it is (d3-f-design › build_declared); the built-in default; who may edit it.
  • Call: the design (Design › declared's table gains a row) → the ticket for the builder: where it is read, its shape, the default, what a bad line does → this skill's table gains the row when it is released.
  • Rules: R-design-9, R-custom-3. Reuse the lookup of Nav: read when published and on start, fall back whole or per line, tell whoever can fix it. A surface for one project's own roles, statuses or pages is a later design: say so, don't build it.
  • Errors: —
  • Gotchas: —

Errors

  • E_INHERITED — a topic of that name is inherited from a base → edit it there, or use the project's own surface. see #surface_edit
  • E_NOT_FOUND — no such topic on the project or its bases → the built-in value is in use. see #surface_find