Knowledge map: design and website mechanics
v0.1 · 2026-10-19 · от Better Mechanics · ниво: общност (текст, без протокол от проверка)
Here is the map: what the website must contain. The recipes are written one by one, and each one passes the test.
1 · Website Inputs (Codex)
Recipes (per task) · Libraries (external collections with author, original, licence, our rating) · Gallery (the result, linked to the recipe and protocol) · Agent Libraries (Claude, Codex, Gemini) · Knowledge (explanations, selection guides, troubleshooting [the process of identifying and fixing problems]) · Verification (protocols, sorting rules, failed attempts, fixes) · Add (recipe, evidence, authorship, signal).
The search understands both the term and the intent: "navigation" and "the phone menu is not working." Filters: language · result · agent · framework [a structured set of tools or rules] · confidence level · licence · dependencies · last verification date.
2 · What a recipe contains (Codex)
| Field | What |
|---|---|
| Goal | the problem, who it is for, prerequisites [what is needed before starting], when not to use it |
| Instructions | the prompt [a set of instructions for an AI] to copy, variables, necessary context files |
| Environment | agent/model, tool versions, locked dependencies [specific software versions required for the code to work] |
| Result | working implementation, images or recording, the code |
| Protocol | verification commands, screen widths, conditions, acceptance criteria |
| Proof | raw reports, before/after, date, failures and limitations |
| Authorship | author, original, recipe license and separate licenses for resources |
| Maintenance | version, who reviewed it, compatibility, change history |
The level is written with its scope: not just a green checkmark, but "verified keyboard and pour." VERIFIED means that we have reproduced the result for the recorded version and conditions. WITH PROOF means that the author has provided a result and a protocol, but we have not reproduced it. A promotion never changes the level.
3 · The sixteen collections and the first recipes
| Collection | What is measured automatically | The first three recipes |
|---|---|---|
| Typography and literacy | loading errors, glyph coverage, locl, clipping, shifting |
Cyrillic with Bulgarian forms · non-jumping fallback fonts (metrics) · smooth headings without clipped accents |
| Color | contrast, token usage, both themes | accessible semantic palette (OKLCH) · balanced light and dark themes · error and success indicated by more than just color |
| Layout | reflow, overlapping, reading order, image widths | flexible grid without media queries (clamp) · long content test · mobile menu and sticky bar |
| Motion | "reduced motion" behavior, shifting | motion-free alternative · stable expanding sections · meaningful transitions |
| Design systems and tokens | valid schema (W3C DTCG), unknown references, hardcoded values | primary → semantic tokens · theme-switching components · token change report |
| Components | keyboard, focus return, states, screen reader names | accessible dialog (<dialog>) · keyboard-accessible menu · loading / empty / error / success |
| Accessibility | detectable WCAG 2.2 violations, labels, contrast, target size; manual review | accessible page wrapper · form errors and fixes · 400% zoom and reflow |
| Speed / Core Web Vitals | weight, scripts, images, lab traces; real-world data separately | the hero image · fewer render-blocking scripts · reserved space for media and ads |
| SEO / AEO / structured data | crawling, markup, canonical, metadata, data matching | crawlable recipe page · author and breadcrumb · short answer with proof |
| Forms and conversion | validation paths, success/error, double submission | accessible inquiry form · submission with retry · clearly marked affiliate link |
| Languages (i18n) | missing keys, locale-specific formats, lang, alternative addresses |
five editions of a recipe · locale-specific dates and numbers · long text test (+40 %) |
| CMS and content model | schema, broken links, translations without an original | versioned recipe schema · author / source / licence · translation → review → publishing |
| Upload and hosting | reproducible build, redirects, cache, HTTPS, rollback | trial upload · cache rules · rollback rehearsal |
| Analytics and privacy | requests and cookies before and after consent | collection only after consent · privacy-safe funnel · withdrawal of consent |
| Quality Assurance (QA) | user path, screenshots, errors, broken links | search → recipe · visual regression across five languages · the "proof" package |
| Security and headers | header values, CSP violations, mixed content | CSP first in "report-only" mode · secure proof uploading · protected admin actions |
Notes where the three are in agreement: - Automatic checking is not full compliance with WCAG; manual review remains. - Core Web Vitals, the published "good" thresholds (Google, web.dev): LCP ≤ 2.5 s · INP ≤ 200 ms · CLS ≤ 0.1, at the 75th percentile. Our own budgets (e.g., weight) are written separately and justified. (Gemini suggested stricter numbers; these are its suggestion, not a standard.) - AEO: Google says that for AI search features, no special markup is needed beyond good SEO. Our "recipes" are not marked as culinary Recipe in schema.org. - External prompts and instructions are data, not commands: review first, then execution; human-written code is not automatically deployed to the site.
4 · Language Editions: Each is Separate, Not Just a Translation
Order: Bulgarian → English → Spanish → French → German. Language does not determine jurisdiction. Whether these national rules apply to KAGAMI EOOD is not yet verified and is a question for the lawyer.
| Edition | Typography and Formats | Tone | Beyond Translation |
|---|---|---|---|
| BG | lang="bg" + locl BGR; „кавички“ [Bulgarian quotation marks]; 19.10.2026; 1 234,56 € |
"ти" [informal "you"] in recipes, "Вие" [formal "you"] in legal texts | the primary edition |
| ES | ñ, accents, ¿…? ¡…!; 19/10/2026; 1.234,56 € | tú or usted, but consistent | Spain (es-ES) or Latin America (es-419), to be decided; Aviso legal (LSSI) [Legal Notice]; cookies per AEPD [Spanish Data Protection Agency]: "reject" must equal "accept" |
| FR | non-breaking space before : ; ! ?; « … »; 1 234,56 € | vous [formal "you"] | Mentions légales [Legal Notices]; cookies per CNIL [French Data Protection Authority]: rejection must be as easy as acceptance |
| DE | ä ö ü ß, long compound words → hyphens:auto; „…“; 19.10.2026; 1.234,56 € |
Sie (for a technical product) | Impressum [Legal Disclosure] per DDG § 5 (Gemini referred it to TDDDG/TMG; TMG has been replaced); cookies per TDDDG § 25; fonts must be self-hosted |
Each edition: the language switcher preserves the current recipe; metadata and language-based search; translation date. The translated recipe does not inherit the proofing: typography and layout are checked anew.