ColorCraft Technical English is the project-specific standard for technical writing. The standard is informed by principles from ASD-STE100 Simplified Technical English.
ColorCraft does not claim formal ASD-STE100 compliance. This standard does not reproduce the ASD-STE100 controlled dictionary.
Use this standard to make instructions clear, consistent, ready for translation, and safer for AI-assisted maintenance. Current application code, API schemas, and tests remain the source of truth for behavior.
Product-specific color-science terms are permitted when this document defines them and writers use them consistently. Do not rewrite exact commands, API fields, routes, color values, filenames, paths, formulas, schema versions, HTTP status codes, or code.
Apply the strongest rules to:
docs/getting-started.mddocs/user-guide.mddocs/troubleshooting.md- Installation, startup, upload, palette, Review, Export, and recovery procedures
Apply controlled terminology and direct technical prose to:
docs/api-contracts.mddocs/architecture.mddocs/color-analysis.mddocs/testing.mddocs/runtime-configuration.mddocs/persistence-and-privacy.mdCONTRIBUTING.md
Preserve formulas, schemas, identifiers, and necessary technical detail.
Use clear product language in:
README.mddocs/brand-system.md- Product positioning and design rationale
- Changelog entries and pull request descriptions
Level 3 permits more flexible sentence structure. It does not permit vague, inflated, or misleading claims.
- Use one preferred term for one concept.
- Do not change terminology only to avoid repetition.
- Use active voice in procedures. Write Select Review, not The Review view should be selected.
- Start each procedural step with an action.
- Put one primary action in each numbered step.
- Put a condition before its action. Write If the API is not ready, wait for the readiness check.
- Use short, direct sentences. Review a sentence when it is longer than approximately 20 words.
- Avoid ambiguous pronouns.
- Identify the actor, such as the user, ColorCraft, the frontend, the API, the extraction service, or the browser.
- Use must for a requirement, should for a recommendation, can for capability, and may only for permission or possibility.
- Give a recovery action for each recoverable error.
- Explain the consequence before a destructive action.
- Preserve exact technical strings and exact UI labels.
- Use parallel grammar in lists.
- Avoid promotional language and generic AI language.
- Do not present subjective design quality as objective fact.
- Keep geometric analysis separate from aesthetic judgment.
- Keep contrast results separate from claims about complete accessibility.
- Distinguish measured values from recommendations.
- Label notes, important information, warnings, results, and examples consistently.
Use Warning only when an action can cause data loss, exposure, or another material adverse result. Use Important for a constraint that can prevent a procedure from succeeding. Use Note for useful additional information.
Use this structure when a task needs more than a short command:
State what the procedure does.
State requirements, limits, permissions, and effects on current work.
Use numbered action steps.
State the expected observable result.
State what to check when the result does not occur.
Example:
Purpose
Start ColorCraft in one terminal.
Before you start
- Install Python 3.11.
- Install Node.js 20 or newer.
- Install the backend and frontend dependencies.
Procedure
- Open a terminal in the repository root.
- Run
.\backend\.venv311\Scripts\python.exe dev.py.- Wait for the API readiness check.
- Open
http://127.0.0.1:5174.Result
The web application opens. The API listens on
http://127.0.0.1:4100.Recovery
If startup reports a port conflict, stop the process that uses the reported port or configure a different port.
Write errors in this order:
- State the problem.
- State the cause when the cause is known and useful.
- State the recovery action.
Examples:
- ColorCraft cannot reach the API. Start the API, and then retry the action.
- ColorCraft cannot copy the export to the clipboard. Select the generated preview, and then copy the text manually.
- The source image is larger than the API upload limit. Select an image that is 10 MB or smaller.
Do not expose stack traces, local absolute paths, environment values, image contents, clipboard contents, or unrelated palette data in user-facing errors.
| Preferred term | Meaning | Usage constraint |
|---|---|---|
| source image | The image that the user uploads for color extraction. | Do not substitute input asset, source media, uploaded visual, or incoming image. |
| palette | The ordered set of colors in the current ColorCraft workspace. | Do not substitute color set, collection, theme, or scheme. |
| palette color | One color in the current palette. | Use color when the context is unambiguous. |
| extracted color | A palette color returned by color extraction. | Do not use for a manually added or suggested color. |
| suggested color | A color proposed in Suggestions. | Do not call it an extracted color. |
| base color | The palette color selected as the start of a suggestion approach. | Preserve this term in Suggestions procedures. |
| swatch | The visual sample that represents one palette color. | Do not use as a synonym for the color value when the distinction matters. |
| color extraction | The process that derives representative colors from a source image. | Do not substitute generation, scanning, image analysis, or palette creation. |
| processing sample | The deterministic pixel sample used by color extraction. | Do not imply that the sample contains every source-image pixel. |
| population | The proportion of the processing sample assigned to a cluster. | Do not describe this value as complete-image population. |
| sampled pixel count | The number of processing-sample pixels assigned to a cluster. | Preserve the API field pixelCount. |
| representative color | The sampled RGB medoid nearest a LAB cluster center. | Do not call it an average, converted LAB median, or exact dominant color of the complete source image. |
| harmony relationship | A detected geometric hue relationship. | Do not use harmony as an automatic judgment of visual quality. |
| relationship fit | A value from 0 through 100 that summarizes relationship confidence and meaningful-hue coverage. | Never substitute harmony score, palette score, quality score, beauty score, or aesthetic score. |
| relationship confidence | The confidence value for one detected harmony relationship. | Keep separate from relationship fit. |
| angular deviation | The measured difference between detected and expected hue geometry. | State the unit when it is not already clear. |
| meaningful hue | A hue with enough saturation to provide geometric evidence under the current algorithm. | The current minimum saturation is documented in color-analysis.md. |
| contrast ratio | The relative-luminance contrast between two assigned colors. | A ratio is a measurement, not a complete accessibility result. |
| displayed contrast ratio | The readable contrast ratio shown in the interface. | Preserve enough precision that a failing value does not appear equal to or greater than its threshold. |
| contrast pair | Two colors evaluated together for contrast. | State the roles when the pair is role-based. |
| text contrast check | A contrast-role check that applies WCAG normal-text or large-text thresholds. | Do not apply text badges to borders or focus indicators. |
| non-text component contrast check | A contrast-role check that applies the 3:1 color threshold to a component boundary or state. | Do not claim complete component accessibility. |
| focus-indicator color contrast check | A 3:1 check for one focus-indicator and adjacent-color pair. | Size, area, thickness, visibility, and focused-versus-unfocused appearance remain outside the calculation. |
| color role | A semantic interface role assigned to a palette color. | Current labels are Page background, Surface, Primary text, Secondary text, Primary action, Action text, Border, and Focus indicator. |
| role assignment | The association between a stable palette color identity and a color role. | Do not describe an active role as a HEX association or expose the internal ID. |
| contrast-role check | A typed contrast test between two meaningful assigned color roles. | Identify whether the check is text, non-text component, or focus-indicator color contrast. |
| all-pairs text contrast matrix | The advanced matrix that applies text thresholds to every palette color pair. | Keep separate from typed contrast-role checks. |
| suggestion approach | One method that proposes colors from a base color. | Current API approaches include complementary, triadic, analogous, split-complementary, tetradic, rectangular, monochromatic, double-complementary, and shades and tints. |
| canonical suggested color | The final RGB and HSL color returned after range limits and RGB canonicalization. | Describe changes from the canonical base color. Use percentage points for saturation and lightness differences. |
| common associations | Context-dependent conventional associations for a suggestion approach. | Preserve the API field commonAssociations. Do not present associations as measurements or guaranteed effects. |
| transitional hue | A meaningful hue greater than 60 degrees and less than 120 degrees in temperature evidence. | Keep separate from neutral colors, which do not provide meaningful hue evidence. |
| Review | The application view that contains palette analysis. | Preserve capitalization when referring to the UI destination. |
| Overview | The Review tab that summarizes the current analysis. | Preserve capitalization. |
| Harmony | The Review tab that presents detected geometric relationships. | Preserve capitalization. |
| Contrast | The Review tab that presents role assignments and contrast results. | Preserve capitalization. |
| Suggestions | The Review tab that proposes optional colors. | Preserve capitalization. |
| Export | The application view that formats the current palette for external use. | Preserve capitalization. |
| export format | One supported representation of the current palette. | Current labels are CSS custom properties, JSON, Tailwind theme colors, and SVG swatch sheet. |
| exported file | A file that the browser creates from the current palette. | Do not imply that ColorCraft stores the file. |
| ColorCraft JSON | The portable, single-palette JSON format that ColorCraft exports and imports in the browser. | Distinguish its schema version from the IndexedDB saved-palette schema and backend API schemas. |
| portable color key | A deterministic document-local color reference such as color-1 in ColorCraft JSON version 3. |
Do not call it an internal workspace ID. |
| semantic role token | An assigned --role-* CSS alias or role-* Tailwind key generated from a color role. |
The Tailwind role-* namespace is reserved. Keep CSS base --color-* and semantic --role-* tokens separate. |
| imported palette | A validated ColorCraft JSON palette activated in the current session. | State that it remains unsaved until Save palette is selected. |
| copy | Place generated export text on the system clipboard. | Do not use as a synonym for export or download. |
| download | Save generated export data as a local file through the browser. | Do not use as a synonym for copy. |
| current session | The active in-memory application state in the current browser tab. | State separately whether data is saved in IndexedDB. |
| unsaved palette | A current palette that has no saved palette record. | Unsaved changes are session-only. |
| saved palette | A versioned palette record in the browser's IndexedDB database. | Do not imply an account or cloud copy. |
| Palette Library | The Library view that lists saved palettes in the current browser origin. | Use Library for the navigation label. |
| local | The application runs on the current computer or configured local network. | Do not use as an automatic synonym for private, secure, offline, anonymous, or persistent. |
| Loopback only | The shell status for resolved loopback hosts and browser origins. | Preserve capitalization. Do not substitute Local only. |
| LAN enabled | The shell status when a resolved host or browser origin is non-loopback. | Do not imply authentication, privacy, or transport encryption. |
| source-image preview | The in-memory browser preview of the current source image. | ColorCraft does not store source-image bytes in the Palette Library. |
A palette is the ordered set of current colors. A color scheme can describe a theoretical arrangement. Do not use both terms only for variation.
Color extraction derives representative colors from a source image. Analysis evaluates a palette. A manual palette can be analyzed without extraction.
A harmony relationship describes measured palette geometry. A suggestion proposes an optional palette change. A detected relationship does not instruct the user to change the palette.
Relationship fit describes hue geometry. Contrast describes relative luminance. A strong relationship fit does not imply sufficient contrast. Sufficient contrast does not imply a strong harmony relationship.
Contrast evaluation measures one accessibility requirement. A passing contrast result does not prove complete WCAG conformance or complete interface accessibility.
Write The assigned text and background colors meet WCAG AA contrast. Do not write The palette is accessible or The design is WCAG compliant.
Population and pixelCount describe the deterministic processing sample after
resize and transparency handling. These values do not count every decoded
source-image pixel.
Export creates text or a file outside ColorCraft. Export does not create or update a saved palette record. Save palette and Save changes write the current palette to IndexedDB.
Copy sends generated text to the clipboard. Download creates a file through the browser.
New palette clears current session work after any required confirmation. Delete palette removes a saved palette record from IndexedDB. Do not call session reset deletion.
Add a terminology entry when a stable product concept has no preferred term. Verify new entries against application code, API contracts, and tests. Update the canonical document instead of copying large explanations into the README.