CBDF Specification: Styles Section

1. Overview

The Styles section defines all visual formatting used in the document. It sits between the first FS (end of Meta) and the second FS (start of Text). It begins with a 4-byte LE length prefix.

Structure (after the FS marker):

[Length: 4 bytes LE] [Layout byte] [Background style] GS [sub-tables...]

The 4-byte length prefix counts the section content bytes only (everything after the length field itself). This is consistent with Document Structure spec Section 4A.

The section is organized into sub-tables separated by GS (0x1D). Each sub-table defines a category of styles (text, container, border, etc.). Empty sub-tables are represented as GS immediately followed by the next GS or FS.

If the meta section contains a "default style set" flag (value >= 1), the styles section may be empty or contain only delta overrides.

2. Layout Byte (1 byte)

The first byte of the Styles section selects one of 256 predefined page layouts. Each layout defines the arrangement of top-level panels.

Bit layout:

The Main panel is ALWAYS implied (never needs a flag).

Common Layout Reference Table

Decoding example for 0x3F (0011 1111):

• Bits 0-3 = 1111: Header(1) + Footer(1) + Left(1) + Right(1)
• Bits 4-5 = 11: 4 columns
• Bits 6-7 = 00: 1 row
• Result: All panels, 4 columns, 1 row.

Click diagram to open full size in new tab

3. Sub-Table Header Byte

A Note About "Tiering"

In this spec, "tiering" means that a style record can have different sizes depending on how many properties you need.

Think of it like ordering a burger: small, medium, or large. You don't pay for the large if you only need the small.

Example with Text Styles:

• Base tier (8 bytes): Font, size, bold/italic flags, text color, background color. This covers 90% of use cases.
• Extended tier (12 bytes): Everything in base PLUS text shadow, letter spacing, line height. For documents that need more control.
• Rare tier (16 bytes): Everything in extended PLUS font effects (flames, glow, etc.), text direction (RTL), word spacing. Only for heavily styled documents.

This saves bytes because most simple emails only need base tier styles. A plain email with 3 text styles uses 3 x 8 = 24 bytes for text styling. If we forced the rare tier for everyone, it would be 3 x 16 = 48 bytes -- double the size for properties nobody used.

The trade-off: if you have 10 simple styles and 1 style that needs a shadow, all 11 become extended tier. You "waste" 4 bytes on each of the 10 simple ones. But this is still better than per-record variable sizing, which makes parsing much harder.

Click diagram to open full size in new tab

Each sub-table (after the layout byte and background style) begins with a 1-byte header:

This is ONE byte, appearing ONCE per sub-table. ALL records in that sub-table use the SAME tier size. The parser reads the header, knows the record size and count, and parses all records sequentially.

Not all sub-tables use tiering. Sub-tables with fixed-size records (shadow, composite, nav bar) only use the count field (bits 2-7) with tier bits = 00.

4. Sub-Table Order

Sub-tables appear in this fixed order, separated by GS (0x1D):

Empty sub-table: [GS] immediately (header byte with count=0, or just GS).

The page-level background style appears BEFORE the first GS and after the layout byte. It is a single record (not a sub-table) using the Container Background Style format.

Click diagram to open full size in new tab

5. Page-Level Background Style

Immediately after the layout byte, before the first GS, sits a single background style record for the entire page (Layer 0). This uses the Container Background Style format (see Section 6A).

If the first byte after the layout byte is GS, the page has no background style (transparent/default).

6. Style Record Formats

6A. Container Background Style

All tiers are FIXED SIZE to maintain sub-table indexability. Gradient color stops have a fixed count per tier (0, 2, or 4 stops).

Base tier (6 bytes) -- no gradient:

Extended tier (12 bytes) -- 2 gradient stops:

Rare tier (20 bytes) -- 4 gradient stops + animation:

6B. Container Border Style (9 bytes, fixed)

6C. Container Spacing Style (4 bytes, fixed)

All values are percentages of the parent container.

The "Egg" (content area) size = container - margin - border - padding. If top/bottom margin = 0, it inherits the left margin value.

6D. Container Shadow Style (4 bytes, fixed)

6E. Container Composite Style (5 bytes, fixed)

Cross-references into the other container sub-tables:

This design allows sharing: multiple panels can reference the same border style, same spacing, etc. without duplication.

6F. Text Style

Base tier (8 bytes):

Extended tier adds 4 bytes (total 12):

Rare tier adds 4 bytes (total 16):

6G. Font Effect (4 bytes, fixed)

For effects that need more parameters than the 4+4 bits in the text style rare tier. Referenced by effect ID 15 ("Custom") in the text style.

6H. Nav Bar Style (12 bytes, fixed)

6I. Table Style (6 bytes, fixed)

6J. Image Definition (8 bytes, fixed)

Defines how an image is displayed. Does NOT contain image data (that's in the Resources section).

When the Resources section is skipped (abortable download), the renderer uses Width and Height to display a placeholder box.

6K. Frame/iFrame Definition (8 bytes, fixed)

7. Complete Styles Section Layout

[Length: 4 bytes LE]
[Layout byte: 1 byte]
[Page background: BG record (variable if extended/rare tier)]
GS [Header: 1B] RS [BG record 0] RS [BG record 1] ...        -- BG styles
GS [Header: 1B] RS [Border 0] RS [Border 1] ...               -- Border styles
GS [Header: 1B] RS [Spacing 0] RS [Spacing 1] ...             -- Spacing styles
GS [Header: 1B] RS [Shadow 0] RS [Shadow 1] ...               -- Shadow styles
GS [Header: 1B] RS [Composite 0] RS [Composite 1] ...         -- Composite styles
GS [Header: 1B] RS [Text 0] RS [Text 1] ...                   -- Text styles
GS [Header: 1B] RS [Effect 0] RS [Effect 1] ...               -- Font effects
GS [Header: 1B] RS [Nav 0] RS [Nav 1] ...                     -- Nav bar styles
GS [Header: 1B] RS [Table 0] RS [Table 1] ...                 -- Table styles
GS [Header: 1B] RS [Image 0] RS [Image 1] ...                 -- Image defs
GS [Header: 1B] RS [Frame 0] RS [Frame 1] ...                 -- Frame defs
GS                                                             -- Reserved (forms)

Minimum styles section (no styles, just structure):

[0x00 0x00 0x00 0x02] [0x00] [GS][GS][GS][GS][GS][GS][GS][GS][GS][GS][GS][GS]
(4-byte length=2, layout byte=0x00 (main only, no bg), 12 empty GS markers)

8. Record Size Summary

All style record types have FIXED sizes within each tier. There are no variable-length records. This guarantees that the parser can index into any sub-table by offset: record_offset = header_size + (index * record_size).

- means that style type does not use tiering (only one fixed size).