About

What this is

The Tomatico UI Style Guide is the shared reference for Tomatico's digital products — websites, web applications, dashboards and internal tools. It exists so that two people building two different screens make the same decisions without having to talk to each other first.

It is modelled on the WFP UI style guide, which organises a design system into Basics, Components, Patterns and Resources. That structure is a good one and it is used here, with two Tomatico-specific additions: a first-class Bilingual and RTL pattern, because the company works in Arabic and English, and a Pattern page, because the brand has one.

Sources

Everything about the brand comes from documents supplied by Tomatico. Where the two disagree, the newer one governs digital work.

Decisions the brand documents do not cover — the derived grey ramp, the semantic token layer, the space and radius scales, the status colours, the component APIs — were made for this system and are marked as such on the page where they appear. Anything labelled derived is an interface extension, not a brand rule.

Why not build on the WFP UI Kit

WFP publishes an actual component library alongside its style guide — uikit.wfp.org, shipped as @wfp/ui and @wfp/icons on npm under Apache-2.0. It was evaluated as a foundation for Tomatico and deliberately not adopted. The reasoning is recorded here so it does not have to be re-litigated.

The decisive one is right-to-left. Retrofitting logical properties into someone else's 930 KB stylesheet is more work than writing 40 KB that is bidirectional by construction — and the result would still be a WFP-shaped system wearing Tomatico's colours.

What the Kit is useful for is coverage. Its component taxonomy — Navigations, Content Related, UI Elements, Forms, Layout — and its page templates (login, complex form, wizard form, table with filter, 404, not authorized) are a good checklist of what a complete system eventually needs, and they inform the roadmap below. The licence permits reading and borrowing from the implementation too, if a specific component is worth studying.

How the site is built

Static HTML, generated from source fragments by a small Python script. No framework, no npm install, no build server. The output in docs/ is committed, which is what GitHub Pages serves.

site/
  nav.json              navigation order and page metadata
  templates/layout.html the page shell
  pages/**.html         one content fragment per page
  assets/css/           tomatico-ui.css and guide.css
  assets/js/guide.js    progressive enhancement for this site

tools/
  build_site.py         renders site/ into docs/
  build_assets.py       derives web logos and pattern tiles from the masters
  split_brand_book.py   split the single-canvas brand PDF into sections (its
                        130MB source is no longer in the repository)

docs/                   the published site

# Rebuild the site after editing anything under site/
python tools/build_site.py

# Check whether docs/ is up to date, without writing (for CI)
python tools/build_site.py --check

# Preview locally
python -m http.server 4173 --directory docs

The navigation, the table of contents and the previous/next links are all generated, so adding a page means adding a fragment and an entry in nav.json — nothing else needs editing.

Versioning

The guide follows semantic versioning, and the version applies to the whole system — the stylesheet and the documentation move together.

• Patch — a fix or a clarification that changes no markup you have already written.
• Minor — new components or tokens. Existing markup keeps working.
• Major — a renamed or removed token or class. Breaking.

This is v0.1.0. While the major version is 0, names may still change: pin the version you build against rather than tracking the latest.

What is missing

Being honest about the gaps is more useful than implying the system is complete.

Assets

• No vector logo. Only raster masters were supplied. An SVG or EPS of the icon and wordmark would keep the logo sharp at any size, let it be recoloured with currentColor, and allow a theme-aware SVG favicon. This is the single most valuable thing to request from the brand's designer.
• No icon library. The icons used in these examples are inline SVGs drawn for the demonstration. A real product needs a consistent set, drawn to match the logo's geometry and stroke weight.
• No Figma library. The tokens exist only in CSS. Designers are currently working from this page rather than from components.

Components

• Modals and dialogs
• Tooltips and popovers
• Toasts and transient notifications
• Pagination
• Menus and dropdowns
• Date and time pickers
• File upload
• Loading and skeleton states
• Charts and data visualisation — which will need a considered answer to what a monochrome palette does with six data series

Page templates

Whole-page starting points, assembled from the components. The WFP Kit's template set is a reasonable checklist of which ones earn their place:

• Sign in
• A long form split across steps
• A filtered data table
• Application shell — masthead, navigation, content
• 404 and not-authorised pages

Elsewhere

• No automated contrast or accessibility test in CI.
• The interactive parts of tabs, drawers and dialogs are specified but not implemented — the CSS gives you the appearance, the behaviour is currently yours to write.
• The Arabic copy in these examples should be reviewed by a native speaker before it is treated as a model for product copy.

Contributing

Two rules keep a design system from turning back into a pile of CSS.

Use what is here before adding to it. If a component almost fits, say so rather than building a variant in your own project — a near-duplicate in an application's stylesheet is how systems die.

Add something once it is used twice. The second time a pattern appears in a product, it belongs here. Adding it involves:

1. Styles in site/assets/css/tomatico-ui.css, built only from existing tokens.
2. A page fragment in site/pages/ with live examples, the markup, and the accessibility notes.
3. An entry in site/nav.json.
4. A check in both themes, both directions, and by keyboard.
5. python tools/build_site.py, and commit the docs/ output with it.

If something here is wrong, or a decision does not survive contact with a real screen, that is worth raising — the guide is meant to be argued with.

Credits

Brand identity, logo, pattern and the brand guidelines: Tomatico's design team, Damascus, Syria.

Typefaces: Poppins by the Indian Type Foundry and Jonny Pinhorn; IBM Plex Sans Arabic by IBM and Bold Monday. Both under the SIL Open Font License 1.1.

Structural reference: the World Food Programme's UI style guide.

The Tomatico name, logo, icon and pattern are Tomatico's property. This guide is published so that people building Tomatico products can use them correctly; it does not license them for other use.