Designer Handbook

If you've built custom sites before (Figma → hand-coded front-end, or a headless CMS like Sanity), you already know how to work on Tortus. You hand-write each section in HTML and CSS; we host it and render the regulated real-estate modules (MLS search, live listings, valuations, lead capture) inside your design as audited, compliant blocks. We also run the content behind them: blogs, market reports, and the team roster.

The core rule

You own the chrome. We own the listing modules.

• Yours: every layout, type choice, color, image, animation, section, page. 100% bespoke. Hand-write the HTML and CSS; we render it faithfully.
• Ours: the actual search results, listing cards, valuation tool, and lead forms. These are governed by the MLS / real-estate boards whose data they show and must render from our components. You don't rebuild them. You drop a token where one goes, and we render the compliant module inside your design.

How it works

Your site is hosted on Tortus, so hosting, SEO, native MLS search, and lead management are built in. You build each section as a Custom Code block in the editor and mix it with our prebuilt blocks.

Quickstart

1. In the editor, click Add Block, open the Layout category, and choose Custom Code.
2. Paste your section's HTML in one field, its CSS in the other. Your CSS is automatically scoped to that block, so .card {} won't leak anywhere else. Write normal selectors; we namespace them for you.
3. Wherever a live real-estate module belongs, drop a {{tortus:…}} token.
4. Repeat per section. Mix Custom Code blocks with our prebuilt ones freely.
5. Publish. Your design is live, with native search, lead management, and SEO underneath.

<!-- HTML field -->
<section class="hero">
  <h1>Park Slope, reimagined.</h1>
  <p>Boutique representation for Brooklyn's brownstone belt.</p>
</section>

<!-- the live MLS search bar renders right here (it posts to the native /search page) -->
{{tortus:search}}

<section class="featured">
  <h2>Current exclusives</h2>
  {{tortus:listings maxListings=6}}
</section>

/* CSS field — auto-scoped to this section */
.hero { padding: 120px 24px; text-align: center; }
.hero h1 { font-family: "Canela", serif; font-size: 64px; letter-spacing: -0.02em; }
.featured { padding: 96px 24px; }

That's a fully custom hero, a live MLS search bar, and a live listings grid: your markup, our data, zero compliance risk.

Placing a module: Custom Code vs. Convert to custom

A Tortus module (listings, team, testimonials, …) can go on a page three ways. They are not interchangeable — this trips people up, so read it once:

The "Pick Manually" picker lives on the block, not on a Custom Code token. A Custom Code block has no config pane, so a token is configured only by the params you type — great for auto/filtered content, but to hand-pick listings or agents you'd be typing IDs by hand. To pick from a visual list, use the block's picker and, if you also want bespoke markup, Convert to custom — which keeps that picker and opens the block's own markup as an editable HTML box plus a scoped CSS box (same {{ field }} / {{tortus:…}} / {{#if}} / {{#each}} grammar as Custom Code; the live data + compliance stay intact via the sealed tokens). (Convert to custom is neither a token nor a Custom Code block; it's the same module, unlocked for full HTML and CSS.)

Token reference

A token is {{tortus:NAME}}, optionally with params: {{tortus:listings columns=4 layout=carousel maxListings=6}}. Params are key=value, space-separated; quote multi-word values (heading="Our Team"). Booleans are true/false, numbers are bare (columns=4). Every field in the tables below is a valid inline param. (These configure a token in a Custom Code block; for the "Pick Manually" picker, see Placing a module above.)

Universal params — work on almost every module

Before the per-token tables, these apply across the board:

Modules with a call-to-action button (valuation, contact, property, search, blog, live_market) also accept the button-style params: buttonStyle (solid/outline/pill/text), buttonRadius (0–40), buttonColor + buttonColorCustom, buttonTextColor + buttonTextColorCustom, showButton (true/false).

The "you own the chrome" default. Because Custom Code is fully bespoke, a module token drops in headerless — just the cards / form / calculator, no "Meet Our Team" band on top — so your own section header is the only one on the page. Want ours instead? Pass a heading (and subheading), or showHeader=true.

Listings & lead modules — the regulated ones

Board-reviewed listing/lead markup. Drop the token; don't hand-author it.

{{tortus:listings}} — curated or auto-pulled listing cards.

{{tortus:valuation}} — "what's my home worth" estimate + lead capture. ⏳ Coming soon — not live yet; the token and options may still change, so we'll document them when it ships. Coming soon →

{{tortus:contact}} — a lead-capture form → the broker's lead inbox.

formType reshapes the form: buyer adds budget + timeline and requires phone; seller adds a required "Property Address" field; newsletter collapses to email-only. (Custom fields are added in the editor's form settings.)

{{tortus:property}} — a single listing's detail view. Params: listingId, source (deal/manual/mls), showPrice · showDetails · showDescription (true), backgroundColor, button-style. Its header is the listing's own address (data-driven), so there's no heading to set.

Where's the search page? Full MLS search is a native page at /search, generated automatically for every site, SSR'd and indexable. It is not added to your nav automatically — link to /search from your nav, a button, or a hero CTA wherever you want an entry point. Its look is configured in the editor's search settings (result-card style, brand, filters) rather than hand-authored in markup, so the results stay compliant and consistent. To drop a search bar inside a custom section, use the {{tortus:search}} token (below).

Backend-fed display modules — the broker's own content, live

These pull the broker's own live data and render it in your section. Never paste stale content.

{{tortus:team}} — the agent / team roster.

{{tortus:blog}} — latest posts.

{{tortus:testimonials}} — client testimonials & synced reviews.

Reviews = testimonials. {{tortus:reviews}} and {{tortus:testimonials}} read the same data (synced Google/Zillow reviews + your own testimonials all live together). {{tortus:reviews}} is just an alternate skin that adds source badges (Google/Zillow) and an outbound "View" link; it takes layout (grid/carousel), sourceFilter (all/google_reviews/zillow/manual), showSourceBadges, showRatings, showImages, maxReviews. Prefer {{tortus:testimonials}} unless you specifically want the platform badges.

{{tortus:market}} — your published market-report editions as an insights feed.

{{tortus:market}} vs. the Market system page. This token is an embeddable insights feed you drop into a section you're designing. The full standalone index is the Market system page at /neighborhoods — use that when you want the whole neighborhood-report surface.

{{tortus:instagram}} — the broker's Instagram feed.

Interactive / data-fed tools

The components where the behavior is ours.

{{tortus:search}} — the MLS search bar (posts to the native /search page). Params: heading ("Find your next home"), placeholder, buttonLabel ("Search"), backgroundColor, button-style.

{{tortus:showings}} — bookable (showing-enabled) listing cards. ⏳ Coming soon — visitor booking isn't live yet; the token and options may still change, so we'll document them when it ships. Coming soon →

{{tortus:live_market}} — a live per-neighborhood pricing spotlight with a trend chart. ⏳ Coming soon — not live yet; the token and options may still change, so we'll document them when it ships. Coming soon →

{{tortus:mortgage}} — interactive mortgage calculator. ⏳ Coming soon — calculators aren't live yet; the token and options may still change, so we'll document them when it ships. Coming soon →

(Map, gallery, and FAQ are editor blocks, not tokens — they're props-only, so you configure them in the editor rather than dropping a bare token.)

Display styles at a glance

Which tokens can change their layout, and how:

Note on the display modules: they render our card layout for each row, dropped into your section — you fully control the section around them (header, spacing, background, surrounding art). The card markup is now editable too: Convert to custom on the block opens its card/section template as HTML, where {{tortus:photo}}-style tokens keep the live photo, price, and compliance intact.

If you mistype a token, it stays visible on the page (e.g. {{tortus:tem}}) so you catch it immediately; it never silently disappears.

Custom navigation header

Building a bespoke nav bar? Convert the header to Custom — the same lossless, reversible path as any other block — and hand‑write its HTML/CSS. (The nav‑style switcher's built‑in starting points are Standard, Centered, and Bold; a fully custom bar comes from Convert to Custom + a chat‑driven rewrite, not a separate "mode.") Inside the converted header a small nav‑specific token set is available (these work only there, and take no params):

The hover sub-menu on the nav reads the --nav-dropdown-* tokens (see the Design tokens reference), so you can restyle the dropdown surface without touching the page background.

Mobile header — fully custom, too

By default your custom header is desktop only: below lg it collapses to the platform's logo + hamburger + drawer. Turn on Custom mobile header in the header settings to hand-write the mobile (<lg) bar and drawer with your own HTML

• CSS — the same nav tokens work, plus {{tortus:menu_toggle}} for the hamburger.

The interactive part is CSS-only. When the menu is open, the header carries data-tortus-nav-open="true" — style your drawer against it, no JavaScript:

<nav class="mn-bar">
  <a href="/">{{tortus:logo}}</a>
  {{tortus:menu_toggle}}
</nav>
<div class="mn-scrim" data-tortus-nav-scrim></div>
<aside class="mn-drawer">
  {{tortus:nav_links}}
  {{tortus:cta}}
</aside>

.mn-drawer { position:fixed; inset:0 0 0 auto; width:80%; max-width:340px;
  background:var(--color-background); transform:translateX(100%);
  transition:transform .3s ease; }
[data-tortus-nav-open="true"] .mn-drawer { transform:translateX(0); }   /* slide in */
.mn-scrim { position:fixed; inset:0; background:rgba(0,0,0,.4); opacity:0;
  pointer-events:none; transition:opacity .3s; }
[data-tortus-nav-open="true"] .mn-scrim { opacity:1; pointer-events:auto; }

• {{tortus:menu_toggle}} opens/closes the menu; tapping a nav link, the CTA, or any element marked data-tortus-nav-scrim closes it (Escape does too).
• Style the hamburger via [data-tortus-nav-toggle] and its [data-tortus-nav-toggle-bar] spans.

System pages

Beyond the pages you build, every site has a set of system pages — routed templates Tortus generates and keeps fed with live data. They appear in the builder's left Pages panel under System Pages, labelled exactly as below. Open one to restyle it: most are block-editable (rearrange, restyle, and Convert to custom like any page), and each per-record detail template nests beneath its index page.

The IDX trio — Search, Building, Listings — is compliance-locked: you style the section around them, never the regulated card/detail markup itself. Everything else (Team, Blog, Market, Developments) is fully block-editable and convert-to-custom.

Heads-up on Market. The left-nav button reads Market, but its public URL and visitor-facing copy are Neighborhoods (/neighborhoods) — same page. Don't confuse it with the embeddable {{tortus:market}} insights feed, which is a token you drop into your own section.

Recipes — starting points

The pattern in all of these: your section header + a headerless module token. You write and style the <h2>; the token drops in just the body. Paste, then make it yours.

Featured listings under your own header

<section class="feature">
  <p class="feature__eyebrow">Now representing</p>
  <h2>Current exclusives</h2>
  {{tortus:listings maxListings=6 backgroundColor="surface-alt"}}
</section>

.feature { text-align: center; padding: 96px 24px 24px; }
.feature__eyebrow { text-transform: uppercase; letter-spacing: 0.18em;
  font-size: 13px; color: #8a8a8a; margin: 0 0 12px; }
.feature h2 { font-family: "Canela", serif; font-size: 44px;
  letter-spacing: -0.02em; margin: 0; }

Meet the team, your layout

<section class="team">
  <div class="team__intro">
    <h2>The people behind every deal</h2>
    <p>Boutique by design — you work with a principal, not a call center.</p>
  </div>
  {{tortus:team columns=4 showBio=false}}
</section>

.team { padding: 112px 24px; }
.team__intro { max-width: 40rem; margin: 0 auto 56px; text-align: center; }
.team__intro h2 { font-family: "Canela", serif; font-size: 40px; margin: 0 0 12px; }
.team__intro p { color: #666; font-size: 18px; margin: 0; }

Editorial testimonials band

<section class="voices">
  <h2>In their words</h2>
  {{tortus:testimonials layout="carousel" carouselPerView="one" cardStyle="quote" backgroundColor="primary"}}
</section>

Use our header when you want it

Prefer our built-in, theme-styled header for a module? Just give it copy — the header turns itself back on:

{{tortus:blog heading="From the journal" subheading="Notes on the market" layout="editorial"}}

The compliance banner (when session recording is on)

If a broker enables Session Recording (a premium feature that replays how visitors move through the site), every published page shows a cookie-consent banner. You don't add it or rebuild it. It appears automatically, and its chrome is governed by a single Tortus design token, complianceBanner:

• Default look: charcoal ink, a thin mint signal rail along the top, a charcoal "Accept all" button. Clean and trustworthy.
• It adopts the broker's brand accent. The accent color tints the top rail and the primary button, so the banner reads as part of their site, not a generic Tortus chrome.
• The wording is fixed. The privacy + session-replay disclosure is compliance-reviewed. You can't edit the copy, and you don't need to.
• It's consent-gated. Nothing records until a visitor accepts analytics, and password / payment fields are never captured.

It's a small fixed banner pinned bottom-center. You control everything around it; you don't restyle the banner itself. The token keeps it consistent and compliant across every broker site. (Token: complianceBanner / complianceBannerFromBrand() in @tortus/design-tokens.)

Art direction & motion level

Every Tortus site is built against one art direction — a complete aesthetic system (type, layout language, color usage, space, signature moves) the build commits to, so the result is distinctive and cohesive instead of a safe generic default. You pick it when you build (or leave it on the default, Editorial Luxury):

Orthogonally, a motion level dials how much the site moves — independent of the look, because parallax taste is personal:

The pick is deterministic: the direction sets the parallax intensity and the reveal timing, and the motion level scales the parallax (Still → none). Both land as the --parallax-speed and --tr-dur CSS vars, so any motion you hand‑write in a Custom Code block automatically matches — see the design‑token reference. Scroll‑reveals always play at a tasteful baseline, and prefers-reduced-motion is always honored.

Motion & loader tokens

Want a preloader, scroll-reveal, parallax, or hover-lift? You don't have to hand-pick durations and easing curves. Every published page (and the editor canvas) carries a --motion-* and --loader-* CSS-var namespace you can animate against from any Custom Code block or converted section. Use them and your motion matches the platform's feel and stays consistent if a broker re-brands. (These follow the brand: loader colors reference the brand color vars, so the spinner is on-brand automatically.)

Motion — durations & easings

/* reveal-on-scroll + on-brand hover lift, from a Custom Code block */
.reveal { opacity: 0; transform: translateY(var(--motion-scroll-reveal-distance));
  transition: opacity var(--motion-duration-slow) var(--motion-easing-decelerate),
              transform var(--motion-duration-slow) var(--motion-easing-decelerate); }
.reveal.in-view { opacity: 1; transform: none; }
.card:hover { transform: translateY(var(--motion-hover-lift));
  transition: transform var(--motion-duration-fast) var(--motion-easing-standard); }

Loader — the preloader / route spinner

/* a brand-aware page preloader */
.preloader { position: fixed; inset: 0; display: grid; place-items: center;
  background: var(--loader-overlay-color); backdrop-filter: blur(var(--loader-overlay-blur)); }
.preloader__spinner { width: var(--loader-spinner-size); height: var(--loader-spinner-size);
  border: var(--loader-spinner-thickness) solid var(--loader-spinner-track-color);
  border-top-color: var(--loader-spinner-color); border-radius: 50%;
  animation: spin var(--loader-spinner-duration) var(--loader-spinner-easing) infinite; }
@keyframes spin { to { transform: rotate(360deg); } }

Widget skins

Backend‑fed widgets already follow your brand (backgrounds, type, text read the --color-* / --font-* tokens). A few small accents are their own tokens so you can recolor them:

/* brand‑colored review stars */
:root { --rating-star-filled: var(--color-accent); }

(The Google / Zillow source badges stay source‑authentic by default so they read as trustworthy; ask us if you want them recolored.)

Want to override any default for a specific site (e.g. a slower, more cinematic preloader, or brand‑colored stars)? Tell us the values and we set them on the brand's design_tokens, and every page picks them up. (Source: motion / loader / widgets groups in @tortus/design-tokens.)

What you can't change (and why)

A short, honest list. None of it limits your design. It's about staying within the rules the MLS boards set for displaying their data. To access an MLS's feed, its listings and the surrounding disclosures have to render a specific way, and a few of these items carry their own compliance requirements on top.

• The listing/search markup itself — render it via the tokens above; don't hand-author listing cards or search results. (MLS IDX/VOW rules.)
• The cookie-consent banner (when session recording is on) — it appears automatically, its copy is compliance-fixed, and it auto-tints to your brand accent via the complianceBanner token. You don't rebuild or remove it.
• The footer's legal strip — the "Powered by Tortus" credit, the brokerage's legal identity + license, the Fair-Housing / SOP / privacy links. Some of this is statutorily required on every public NY broker site (NY RPL §442-h for the SOP link). You can style and arrange the footer, but a small always-present legal line can't be deleted. In the editor, clicking it shows a quiet "managed by Tortus" note instead of selecting it. That's expected.
• Per-listing disclaimers + source attribution — rendered automatically on listings; you don't add or remove them.

Everything else (nav, heroes, galleries, about, team, blog, contact, custom sections, motion, type, color) is yours.

What to send us to get started

So we can stand up your design fast:

1. Your Figma (or live URL / inspiration) for the pages in scope.
2. Per page, a note on where the real-estate modules go: which page is the search/conversion page, where featured listings sit, where the valuation CTA lives.
3. Your fonts (files or Google Fonts names) and brand colors.

We'll get the first page into the editor and share a live preview link you can review and iterate against.

Need something the handbook doesn't cover? Tell us — a lot of what's here started as a designer's request.