Product guidelines

The rules above are the brand. These are the rules for the software built on it (the web console, Cave Shops mobile, Cave POS), and the components in components/ implement them.

• Buttons are rectangles. Use radius-control (10px) for buttons, inputs, selects, menu items and nav items. Pills (radius-pill) are for badges, chips, avatars and the SectionTag, never for actions.
• One primary action per view. Primary is accent-strong with on-accent-strong text (white on lagoon in light, navy on teal in dark). Brand teal stays for marks, tabs and highlights; it is not a button fill and not small text.
• Cards are flat. surface-raised, a 1px border, radius-md, no shadow. Only floating layers (menus, toasts, dialogs, sheets) take shadow-menu or shadow-overlay. Dialogs and sheets use radius-lg.
• Status is never colour alone. Every status carries a word, and an icon where there is room. Use the success, warning, error and info tokens (-bg, -fg, -border, -solid); -solid is for dots, bars and chart marks, -fg for text. Map record states to tones once, in a shared function.
• Type in product. Page titles use page-title and card or dialog titles section-title (Poppins; in Arabic ar-page-title and ar-section-title, Almarai). Hero (English) and Almarai Light (Arabic) are for brand moments: landing pages, sign-in, splash and empty-state headlines at 24px or more. Tables and forms are always Poppins and Almarai.
• Arabic names. In Arabic text the company is كهف, the web product متاجر كهف, the desktop and mobile till نقطة مبيع كهف (never "Cave POS" or "POS"), and the generic term is نقطة المبيع ("the point of sale"). Say "تطبيق نقطة مبيع كهف" for the app, and keep the feminine agreement ("نقطة مبيع كهف المكتبية"). Latin product names stay in English text only, in every screen, notification, message, document and screenshot caption.
• Screenshots. Marketing screenshots (landing pages, store listings) are captured from the current build, in both languages and all three themes (Light, Dark, Black), with sample data, and are retaken whenever the design changes. A page shows the picture for the visitor's language and the theme on screen, and a theme without its own picture (the shop pages' dark is already near-black) uses the nearest one. Products in the till and the shop page show pictures, never empty placeholders. Screenshot tabs that turn by themselves stop for good once the visitor picks one.
• The Cave account. One account serves Cave Shops and Cave POS (and later products), so account screens (sign in, register, forgot and reset password, account settings, link a device, "Sign in with Cave") say Cave (Arabic كهف, the account حساب كهف) and show the symbol, set in display or ar-display. They name the products only in one context line ("One account for Cave Shops and Cave POS"). Product screens (a console, a storefront, navigation) keep the product's name. Page titles, share previews and the copyright line on account screens say Cave. Use the AuthCard component.
• Themes. Light and Dark are the brand's own; Black is for people who prefer a near-black screen. Offer Light, Dark, Black and System. System follows the device: a light device gets Light; a dark device gets the platform's default dark theme, which is Dark unless an administrator sets Black in Platform settings (defaultDarkTheme in appConfig/public, read by the web, mobile and desktop apps and cached on each device so it is right offline and on first paint). Someone who picks Light, Dark or Black themselves always keeps that choice; the setting never overrides it. Never derive Black from Dark by darkening: use the black values in tokens.json. In Black, text on teal fills (on-accent-strong, on-accent, on-danger) is charcoal, which reads better there than navy (5.1:1 against 4.55:1). Everything else, including the status and chart colours, passes on charcoal unchanged. The white logo lockup is approved on charcoal.
• Right-to-left. Build with logical properties (start, end, inline) so one layout mirrors. Numbers, prices, phone numbers, emails, codes and URLs stay left-to-right inside Arabic text (cv-ltr), aligned to the start edge. Mirror directional icons (chevrons, arrows, back) but not logos, checks or media controls.
• Touch and density. Controls are 40px on desktop and 48px on touch; minimum touch target 44px. Tables use body-sm and 12px vertical cell padding.
• Motion. duration-fast (150ms) for hover and focus, duration-base (200ms) for overlays, easing-standard. With reduced motion, drop transitions and keep loops to a slow pulse.
• No gradients, no emoji. The flat-colour rule holds in product. Replace purple or teal gradient banners with flat accent-soft or surface-sunken fields.
• Icons. One rounded line set, 1.75px stroke, 20px (24px in navigation on touch), in ink, ink-muted or accent-text. The three brand icons in assets/Icons are for marketing and empty states, not UI chrome.
• Third-party colours. WhatsApp green (#25D366), Facebook, Instagram, Telegram and Google marks keep their own colours as marks only. Put the label in ink beside them; do not use them as button fills. The one exception is the shop's "Order on WhatsApp" button (see Shop colours).
• Shop colours. A shop's own colour (storefront, and the app's accent for a shop that has the feature) is free: Cave does not restrict the hue. What Cave guarantees is that everything drawn from it stays readable, by role, computed from the colour rather than chosen by the shop:
  • Fill (buttons, bars, badges): the shop colour itself, with text on it of whichever of white or charcoal reads better, at 4.5:1 or more. Where neither reaches 4.5:1 (mid colours near a relative luminance of 0.2, such as many blues and reds), nudge the fill's lightness by the smallest step, keeping its hue, until one does.
  • Colour as text or an icon (links, prices, outlines): a version of the shop colour moved in lightness only (darker on a light surface, lighter on a dark one) until it reaches 4.5:1 for text and 3:1 for icons and outlines on that surface. Never use the raw colour as small text.
  • Tints (selected rows, soft badges): the shop colour at low alpha over the surface, with the text colour from the line above.
  • A colour too close to its surface to be seen as a fill (under 3:1) gets a border-strong outline.
  • Shops cannot change ink, the surfaces, the status tokens, focus-ring or third-party marks: "paid", "error" and the WhatsApp mark keep their own colours. The "Order on WhatsApp" button is the mark's green (#25D366) with charcoal text (8.7:1), never white text (1.98:1).
  • The storefront's dark ground follows the visitor's Cave theme: navy and gray-800 in Dark, charcoal and its raised surface in Black (the platform's default dark theme decides when the visitor follows their device); light is paper and white. The shop's colour is made readable on whichever ground is shown. The visitor's own light or dark choice follows their device by default and is remembered on that device.
  • The same rule applies wherever a shop colour is printed or shared: QR posters, invoices, receipts and share cards.
  • Discounted prices. A plan can carry a regular price beside the price people pay (100 struck through, then 3): the regular price in ink-muted, struck through and smaller, the price now large, the currency and cycle beside it, and one chip with the percent off. The price charged is always the price now. Prices on the landing, the subscription pickers and the apps follow the same pattern. Never show a regular price that is not above the price.
• Add-ons and plans. Every feature and every quantity (branches, products, customers, orders, storage, team seats, image slots) can be an add-on: a feature add-on switches features on, an extra-room add-on adds a number of one allowance per unit. A plan is made of add-ons: it lists the add-ons it includes (includedAddons), and the plan's own features stay the source of truth for what a shop gets. There is no separate "package": every purchasable thing is a plan, and a plan is shown as what it is made of. The rules, on every platform:
  • Add-ons live in one place, the owner's Add-ons page (web console, Cave Shops mobile, and Settings > Subscription in Cave POS), owner only. It shows what is running (with its end date and a Renew action), then what is on sale for the shop's plan, then the order. Use the AddonCard and its order bar.
  • A card that cannot be bought says why in one sentence; it is never hidden and never a disabled button with no reason. An add-on needs what it builds on (a funnel needs analytics): it says so instead of switching the missing feature on behind the shop's back. The plan's own features are never bought twice.
  • The price is per unit, per cycle. The server prices every order and creates the payment; the screen only shows the total first. Whish is first, cash is the fallback an admin confirms, a discount code applies to the whole order, and an order that costs nothing activates at once.
  • Each add-on runs for its own period and ends on its own date. When it ends the shop returns to what its plan includes. Nothing a shop built is deleted when an add-on ends.
  • Admins manage the catalog (name, kind, what it grants, price, regular price, requirements, plans it is limited to, on sale or retired) and list the add-ons a plan is made of, on the web and on mobile. Retiring an add-on stops new sales and leaves existing purchases running.
  • Names, descriptions and units have an Arabic field; an Arabic screen shows the Arabic one.
  • Plan artwork. A plan can carry one picture (imageUrl, an absolute https address, set in Admin > Plans, optional). It is a photograph, 3:2 (1536 x 1024), in the Cave grade: warm light, teal and natural wood, real people at work in a real shop, café or restaurant, the screen shown in the scene being a phone, tablet or till (never invented UI text). No text or logo in the picture: names, prices and sentences are drawn by the app, so Arabic and English share one file. It is shown full width at 3:2, cropped to fill (object-fit: cover, anchored a little above centre, because the subject sits in the upper middle), flush to the top of the card or as one half of the large plan panel, never inside a small letterboxed box. Keep faces and the device away from the outer 10% so crops at 16:7 (the desktop till window) still work. A plan without a picture shows its card as before; a failed download leaves the card whole. Add-on artwork is different: small illustrations that sit in a fixed 48 x 40 slot, contained, so lines without one still line up.
  • Plan details ("See everything"). One view, the same on every platform: a dialog on desktop and a full-screen sheet on a phone. It shows the price, then Included add-ons as a grid of pictures (two columns on a phone, three on desktop) grouped by kind in a fixed order (Selling, Orders, Restaurant, Team, Room, Branding, Insights, AI, More), each with its picture, name, a "+3 branches" chip for extra room, a one-line description and its price on its own; an add-on with no picture shows its kind's icon on the tinted tile so the grid stays even. A line says what the add-ons alone are worth bought separately. Then Room and limits as a two-column table (products, customers, orders a month, team seats, branches, pictures per product, storage in MB or GB, history), leaving out what the plan does not include, then one line: need more, add any add-on. Buttons: Browse add-ons, Close, and Choose {plan} (the same label as the card's button). Every feature is an add-on: a plan's features are never listed as text, they are the add-ons it is made of (the basics are the Online shop page and Orders on WhatsApp add-ons), so a plan is its add-ons plus its limits. An add-on that is no longer on sale is skipped.
• Plans on the landing. Plans are chosen with tabs (name and price), one short panel at a time, not a wall of cards: the plan's photo on one side (stacked above on a phone), then its name, one sentence, the price (regular price struck through, price now, cycle, percent off), three or four short lines (the first may be a caption such as "Everything in Shop, plus:"), one primary button, "Or try everything free for a month" as a quiet second button (the trial is a button, never a card), and See everything in {plan}. The popular plan is selected first. The business tier ("Contact us") and the free desktop till are two quiet strips under the panel. Plans a shop has bought or been given privately are never listed. The card never lists features as text and never lists add-ons: both live in the details.
• Product logos. Each product's footer shows its own logo file (Cave Shops and Cave POS each have one) so a product can get its own mark without touching the code. Cave pages carry it; a shop's own page never does.
• Powered by Cave. Every product says it comes from Cave with one line, "Powered by [Cave mark] Cave" (Arabic: "مدعوم من [mark] كهف"), in the footer of the web pages, under the sign-in cards, at the foot of the Cave POS sidebar. The mark and the name are one link to www.cave.technology. Same design on every platform; see components/PoweredByCave.
• Footer. A product's footer is one centred stack: its own logo, Powered by Cave, the copyright line, and up to five links. The reference is the Cave POS website's; see components/Footer.
• Choosing the colour (Website > Look, shop settings, on every platform): ready-made colours with Cave's own first, a colour-code field and a free picker, and a reset to Cave's colour. Beside it, a small storefront drawn from the derived roles on a light page and on a dark page, so the owner sees what customers see. One plain sentence says what was done: it reads well, buttons got a small shade change, or buttons got an outline. Show the contrast numbers for button text and coloured text. A locked plan shows the same controls disabled with one line saying which plan unlocks them. Never reject a colour; adjust and explain.
  • Preview while editing (web Website tab): the storefront itself, framed at phone, tablet or desktop width and in the light or dark page, updated as the owner types, so a change is seen before it is saved or published.
• Charts. A single series uses chart-1. Ordered series (stages, levels, depth) step through the depth ramp (seafoam, teal, lagoon, deep-teal, abyss). Unordered series take chart-1 to chart-4 in order, at most four, with direct labels and the values in a table or tooltip; group the rest as Other. Status series (paid, owed, overdue) use the *-solid status tokens, not the chart colours. Never rely on colour alone: label the series.
• Tutorial videos. Cave's YouTube tutorials all follow one style, made by tool/tutorial_video in the Cave POS repository (its STYLE.md is the rulebook and build.py <slug> lint checks it). One task per video, 1 to 2 minutes: intro (logo, Hero title, one line), an overview picture, numbered steps, an optional "Good to know" with up to three icon cards, and an outro that points to the live plans, the website and Powered by Cave. A video never states a price, a plan name or a limit (they change, the video does not); it says "part of selected plans, or add it to any plan" and sends people to the live plans page. Only real app screens, in a monitor frame with the Footer's shadow, on surface with ink, ink-muted, lagoon actions and one teal highlight at a time; Hero for the display title and Poppins for everything else (Almarai Light at 1.18 times for Arabic). Sound has three layers: a clear voice, a soft music bed about 11 dB under it, and small cues (a pop, a tick, a chime), mastered to -16 LUFS. Every video ships with a voice-only copy, a 1280x720 thumbnail (teal split, product badge, a three-line Hero title, one white chip, the real screen), captions and upload notes. The list of titles is VIDEOS.md, and the prompt to ask for a new video (a topic, or none to take the next title) is PROMPT.md, also shown in the web console under Admin > Platform settings. Titles read "Product Tutorial: what you get" in 70 characters or fewer. The channel is one company channel, Cave, with one playlist per product (Cave POS, Cave Shops) plus Getting started and Tips and tricks; Arabic videos are separate and use the Arabic names.