How to document responsive logo behavior for developers

Most logo bugs in production are not drawing bugs. They appear because a developer had to guess when the wordmark should collapse into a mark, what the minimum legible size is, and which file is safe on a dark background. A design team approved a mark in Figma; the engineering team shipped three inconsistent versions across breakpoints. A short, explicit document about how the logo behaves across screen sizes prevents that drift, and it does not need a 40-page brand book to do the job.

This is a working method for how to document responsive logo behavior for developers, written for brand designers, design system owners, and front-end leads who hand a mark to engineering without endless Slack threads. The output is a one-page behavior spec, an asset matrix, breakpoint rules, and a handoff format a developer can implement on day one.

How to document responsive logo behavior for developers

Start with a single page that answers four questions in plain language: which file is used where, how the mark resizes, which variant appears on which background, and what to do at the edge cases such as very small viewports, print, and email. Everything else in the brand system is secondary. If a developer cannot answer those four questions in under five minutes, the documentation is not doing its job.

The most common reason responsive logo behavior goes undocumented is that the team assumes the SVG and the CSS will just work. They do not. SVGs render differently across browsers, the inline wordmark wraps at narrow widths, and the brand-approved clear space gets eaten by a parent flex container. A short, deliberate document closes the gap between Figma and the shipped product.

What belongs in a responsive logo behavior spec

A behavior spec is not a full style guide. It is a focused reference that sits next to the engineering handoff and answers the questions a developer asks while writing code. The right size for this document is one printed page or one long scrolling screen, no more. The following blocks should always be present.

• A clear statement of the approved logo variants, including the full lockup, the wordmark alone, the logomark alone, and a monogram fallback for very small spaces.
• Breakpoint rules that map each variant to a pixel range, with a default and a documented exception path.
• Minimum and maximum sizes in pixels and in real-world units, measured against the cap height of the wordmark rather than the bounding box.
• Clear space rules expressed as multiples of a logo unit, so the developer can compute the padding in CSS without re-measuring the SVG.
• Background behavior for light, dark, photographic, and colored surfaces, with a single-color fallback for unsupported cases.
• Asset delivery details, including file names, formats, retina handling, and a one-line example of correct usage in HTML.

Keep each section short. The point of a responsive logo behavior spec is to remove decisions from the developer’s plate, not to push the design system knowledge problem onto engineering. If a rule is debatable, leave it out and replace it with a single default plus a named contact who can answer the edge case.

Define the variants before you write any prose

Most brand assets ship with two or three mark variants. The trick is to name them consistently, lock the names early, and use those names everywhere. A small variant map saves hours of is-this-the-icon-version-or-the-symbol-version confusion in code review.

Variant name	Visual description	Primary use	File formats
Primary lockup	Logomark plus full wordmark, horizontal	Default at desktop, marketing pages, email signatures	SVG, PNG@1x, PNG@2x, PDF for print
Wordmark only	Brand name set in the approved typeface, no symbol	Mid-size containers, app store screenshots, slide masters	SVG, PNG@1x, PNG@2x
Logomark only	Standalone symbol or icon, no wordmark	Mobile header, favicon, social avatar at small sizes	SVG, PNG@1x, PNG@2x, ICO for legacy browsers
Monogram	One or two letter initial version, no full wordmark	Sub-200px contexts, watch faces, app tiles	SVG, PNG@1x, PNG@2x
Single color	One-ink version, usually monochrome white or black	Dark or photographic backgrounds where full color fails contrast	SVG preferred, PNG@1x, PNG@2x

Write breakpoint rules in pixels, not vibes

Breakpoints should map to the actual sizes at which a variant starts to break, not to the framework default of 768 pixels. Open the responsive prototype, drag the viewport slowly, and note the pixel width at which the horizontal lockup stops fitting, the wordmark starts to crowd the navigation, or the mark loses its identity at small sizes. Those are your real breakpoints.

Breakpoint range	Active variant	CSS class example	Notes for developers
0 to 359 px	Monogram	.logo--monogram	Disable hover affordance, prefer SVG, center align
360 to 639 px	Logomark only	.logo--mark	Maintain minimum 24 px cap height, no tagline
640 to 1023 px	Wordmark only	.logo--wordmark	Watch for nav collision, allow slight horizontal compression
1024 px and above	Primary lockup	.logo--lockup	Default state, full clear space, tagline allowed

Notice that the ranges are specific and the CSS class names are stable. A developer reading the table can paste the values into a media query list without translating marketing copy into code. For additional background on the structural reasons a mark needs more than one form, the Wikipedia entry covering the history and use of logos also notes that the same mark often needs a long and a short version because a single composition cannot serve every container.

Avoid ranges with gaps. If the design only uses three variants, list three ranges, not four. Gaps force the developer to invent behavior at the missing width, and that is how inconsistent headers are born.

Encode clear space as a math rule

Clear space is the protected padding around the mark where no other element can live. The fastest way to document it is to define a single unit, usually the height of the logomark’s cap or a fixed token such as x = 16 px, and express every padding as a multiple of that unit. The developer can then compute the value in CSS without re-measuring the SVG.

• Minimum clear space on any side: 1x the logo unit.
• Preferred clear space on any side: 2x the logo unit.
• Clear space around the full lockup, both horizontal and vertical: 1.5x the logo unit.
• Clear space between the logomark and the wordmark inside a lockup: 0.75x the logo unit, fixed by the source file.

Write these rules in both pixels and in the chosen unit. The pixel value is what gets pasted into CSS. The unit is what the designer uses to reason about the layout. If the brand later changes the unit, only the conversion rule changes, not the documentation itself.

Specify minimum and maximum sizes by cap height

Documenting size in pixels is risky because the same pixel value feels different on a high-density display. Instead, define a minimum cap height for each variant, and let the developer compute the rendered size from the device pixel ratio. A 12 px cap height on a 2x display is a 24 px asset, and that detail belongs in the spec.

• Monogram minimum cap height: 16 px CSS pixels, regardless of device pixel ratio.
• Logomark minimum cap height: 20 px CSS pixels.
• Wordmark minimum cap height: 14 px CSS pixels, measured on the lowercase x-height.
• Primary lockup minimum height: 28 px CSS pixels in the header, no maximum in marketing layouts.

Cap height is also the metric designers usually check when approving a sample, so expressing the rule in cap height keeps the conversation aligned between design and engineering. If a designer and a developer are using different yardsticks, the mark will end up too small in one place and too large in another.

Background and contrast rules

Responsive logo behavior is not only about width. The same mark that looks fine on a white header can disappear on a dark hero or wash out on a busy photo background. The behavior spec should define what happens in each case and which fallback variant is preferred.

• On light backgrounds, default to the full color primary lockup.
• On dark backgrounds above 60 percent luminance, switch to the single color white version, never recolor the primary lockup at runtime.
• On photographic or patterned backgrounds, prefer the monogram or a contained lockup inside a high-contrast plate, do not rely on CSS filters.
• For email clients that strip SVG, the PNG@2x is the only safe delivery format and the lockup must be pre-cropped to its own background.

Resist the temptation to allow runtime color changes through CSS variables unless the design system explicitly maintains a full set of single-color SVGs. Recoloring a primary mark on the fly is how brand drift begins.

Asset delivery and naming

The asset matrix is the part of the spec that developers actually open during implementation. Make it boring on purpose. Stable file names, a single folder layout, and a one-line HTML example will save more time than any clever component library.

Variant	File name	Format	Recommended use
Primary lockup	logo-lockup.svg	SVG	Default in HTML, retina handled by SVG
Wordmark only	logo-wordmark.svg	SVG	Mid-size containers and app store screenshots
Logomark only	logo-mark.svg	SVG	Mobile header and favicon
Monogram	logo-monogram.svg	SVG	Sub-200 px contexts
Single color white	logo-lockup--white.svg	SVG	Dark or photographic backgrounds
Email fallback	[email protected]	PNG	Email signatures and Outlook clients

Pair the table with a single HTML example, because the developer will copy the example and adapt it rather than write the markup from scratch. A small example clarifies where the alt text goes, how the class names align with the CSS, and whether the SVG should be inlined or referenced as a file. The class names should mirror the variant names from the behavior spec so the two documents feel like one.

Behavior, not just assets: what changes at each breakpoint

The most overlooked part of how to document responsive logo behavior for developers is the description of the transition itself. Variants do not just swap at a pixel width. They often change in height, clear space, alignment, and even which surrounding elements stay visible. Write down the transition so a developer knows what to remove, what to keep, and what to animate.

• When the primary lockup switches to the wordmark, drop the tagline and any decorative dot pattern, but keep the existing alt text so screen readers do not see a new label.
• When the wordmark switches to the logomark, set the height in CSS to the logomark’s cap height, never to its bounding box, because the bounding box includes transparent padding.
• When the logomark switches to the monogram, disable any hover effects and any animation that scales the mark above 100 percent.
• At every breakpoint transition, the click target should remain at least 44 by 44 CSS pixels, even if the visual mark is smaller.

This is also a good place to link out to your brand asset handoff checklist for developers if your team already uses one. The behavior spec covers the rules; the handoff covers the delivery. Each one has a job, and the team reads both.

Accessibility and assistive tech

A responsive logo is not only a visual problem. The alt text, the focus state, and the announcement to screen readers all change with the variant. A good behavior spec calls out what the developer must keep constant.

• Alt text remains the brand name on every variant, for example alt="Acme Studio", regardless of which mark is showing.
• Decorative uses, such as a watermark in a marketing layout, must be marked role="presentation" or use an empty alt attribute.
• The logo link should be the first focusable element in the header, with a visible focus ring that meets the contrast ratio defined in the brand accessibility rules.
• If the design uses an SVG sprite, expose each variant as its own <symbol> with a stable id, not as a fragment URL that the developer has to keep updating.

Focus order, contrast, and motion preferences all sit next to a logo spec, because the same breakpoint that swaps the variant also changes what a screen reader announces. When those three concerns are written down in one place, a developer can audit the header in a single pass.

Motion, animation, and reduced motion

Most marks do not animate, but the responsive spec should still acknowledge the question. A logo that fades in on first paint, pulses on hover, or scales during a page transition can cause motion sickness, can be blocked by a corporate network filter, and can fail a Core Web Vitals test. Two short rules handle most cases.

• No motion on the logo during the initial page load. The mark should appear fully on the first paint and stay still until the user interacts with it.
• Any hover or focus animation must be wrapped in a prefers-reduced-motion check and must keep its duration under 200 ms, with no scaling above 105 percent.

The variant map is also a contract. Once the names are written down, the developer can refer to logo--mark in code and reviewers can spot a wrong variant in seconds. If you want the deeper distinction between a logotype, a logomark, and a full lockup, the piece on logotype, logomark, and logo lockup terminology lays out the structural difference in plain terms and is worth bookmarking in the brand wiki.

When the responsive spec is honest about motion, the developer does not have to invent a sensible default. The behavior is decided, and the implementation can match the design without negotiation.

Versioning and change control

Even a one-page spec goes stale. The variant names change, the breakpoints shift, the minimum sizes get revised, and the design team swaps a typeface. The fastest way to keep the documentation useful is to put a small change control section at the top of the document and treat the spec as a versioned artifact.

• Date the document, in ISO format, at the top right corner, so anyone reading a screenshot can see if it is the current version.
• Number major revisions, for example v1.0, v1.1, v2.0, and link the previous version in a comment for reference.
• Tie the spec to a single source of truth, usually the design tokens JSON or the Figma library, so a change in either one is reflected in the spec.
• Name a single approver, the design lead or the brand owner, who signs off on every behavior change before engineering adopts it.

If the brand has a more detailed visual identity reference, link to it from the spec but keep the responsive behavior doc separate. Two documents, two purposes, one source of truth.

A practical handoff format developers actually read

The behavior spec is only useful if a developer can find it. The most common reason a logo spec is ignored is that it lives in a brand wiki that no one links to from the codebase. The fix is structural, not editorial. Put the spec in the same repository as the assets, and link the spec from the asset folder’s README. A developer opening the SVG will see the rules in the same place as the file.

• Repository location: /brand/logo/README.md, with the SVG files and the spec side by side.
• Asset delivery: a single ZIP or a release tag, named with the version, for example logo-assets-v1.2.zip.
• Front-end reference: a small Storybook story or a single HTML demo page that uses every variant and every breakpoint, for visual regression testing.
• Review checklist: a short list of five to seven questions a reviewer can answer in under a minute, such as does the variant match the breakpoint and is the alt text correct.

The demo page is the part that most teams skip, and it is the part that catches the most bugs. A short, controlled example page lets QA click through every variant in every breakpoint and file a single issue when something looks off. The handoff, the spec, and the example page form a triangle, and removing any one of them makes the other two weaker.

Common pitfalls when documenting responsive logo behavior

Most of the mistakes in a logo behavior spec are not about the mark itself; they are about the surrounding process. The list below is short on purpose, because a long list of warnings tends to get ignored. These are the patterns that have caused real bugs in production at design-led teams.

• Treating the responsive spec as a one-time deliverable instead of a living artifact, so the document drifts away from the implementation within a quarter.
• Letting the developer choose the breakpoint ranges from a framework default, which produces inconsistent behavior between the marketing site, the app, and the email templates.
• Skipping the email and print fallback, which still ship a logo even when the rest of the brand is digital only.
• Asking the developer to recolor the mark at runtime through CSS variables, which leads to off-brand shades and unreadable marks on busy backgrounds.
• Forgetting to set a minimum size on the click target, so the logo becomes a usability problem on touch devices even though it looks correct.

None of these pitfalls are exotic. They all show up in code review, and a short, deliberate behavior spec is the cheapest way to prevent them. The same rules can be extended to other brand assets such as color, typography, and iconography, and a small logo spec is a reasonable place to start before expanding the scope.

A short worked example

To make the rules concrete, imagine a small studio brand with a circular logomark and a lowercase wordmark. The studio ships a marketing site, a web app, and a transactional email. The behavior spec, reduced to its essentials, would read like the table below.

Surface	Variant	Width range	Notes
Marketing site header	Primary lockup	1024 px and above	Default state, full clear space
Marketing site header	Wordmark only	640 to 1023 px	Drop tagline, keep alt text
Marketing site header	Logomark only	360 to 639 px	Cap height fixed at 24 px
Marketing site header	Monogram	Below 360 px	No hover animation, focus ring required
Web app sidebar	Logomark only	All widths	Fixed at 32 px cap height, never resize
Email signature	Primary lockup PNG	All widths	Pre-cropped, no SVG, no animation

The worked example is deliberately short. The point is to show how a real spec collapses the rules from this article into a one-page reference that a developer can implement and a designer can audit in a single sitting.

Maintaining the spec over time

Once the behavior spec is in place, the next challenge is keeping it current. The most reliable approach is to schedule a quarterly review, set a recurring calendar event, and assign a single owner who is responsible for updating the document. The review should answer three questions, no more, and each question should produce a clear yes or no answer.

• Does the spec still match the assets in the repository?
• Do the breakpoints still match the shipped product?
• Has the brand owner approved any pending changes since the last review?

If the answer to any of those questions is no, the owner updates the document, increments the version, and announces the change in the team channel. A spec that is updated quarterly and announced in 50 words is more useful than a spec that is updated yearly and announced in a long meeting.

Bringing it together

A responsive logo behavior spec is a small artifact with a large payoff. It is one page, four tables, and a handful of rules, and it removes most of the guesswork from a developer’s day. The most valuable sections are the variant map, the breakpoint table, the clear space rules expressed in math, and the asset matrix. Everything else, accessibility, motion, change control, is a short paragraph that prevents a specific class of bug.

The next step is small. Pick the last shipped logo bug, write the rule that would have prevented it, and add that rule to the spec. Repeat the exercise for the next bug, and the document will grow into a real working reference within a quarter.

Frequently asked questions

What is a responsive logo behavior spec?

It is a short document that describes how a brand mark changes across screen widths, including which variant is used at each breakpoint, the minimum and maximum sizes, the clear space rules, and the asset delivery details. It is the bridge between a brand book and a developer’s CSS, and it is meant to be one page long, not forty.

How many logo variants should a responsive spec cover?

Most brands need three to five variants: the full lockup, the wordmark alone, the logomark alone, a monogram for very small spaces, and a single-color version for dark or photographic backgrounds. A team should resist adding more variants unless a real use case requires them, because every extra variant increases the chance of inconsistent implementation.

How do I choose the right breakpoint values for a responsive logo?

Open the prototype, drag the viewport slowly, and note the pixel width at which each variant starts to break. Those are the real breakpoints. Avoid using framework defaults such as 768 px without checking the mark, because a 768 px default often crowds the wordmark in a real header.

Should the logo spec use pixels or rems for sizes?

Pick one and document it. Pixels are easier to reason about in design tools, while rems respect the user’s font size preferences. Most modern teams use rems for typography-driven sizing and pixels for container sizes, and they write the rule in the spec so the developer does not have to guess.

Where should the logo spec live in the codebase?

Next to the assets, in a folder such as /brand/logo/, with a README that links to the spec. Keeping the spec in the same repository as the SVG files means a developer opening the file will see the rules in the same place, which is the simplest way to make the documentation stick.

How do I handle logos inside emails?

Email clients vary widely in their support for SVG, retina handling, and CSS. The safest approach is to ship a pre-cropped PNG at 2x, with the brand-approved clear space baked into the image, and to use the same alt text as the web version. Avoid relying on media queries inside the email, because most clients ignore them.

What is the difference between a logomark, a wordmark, and a lockup?

A logomark is the standalone symbol, a wordmark is the brand name set in the approved typeface with no symbol, and a lockup is the combined composition of the two. A behavior spec is clearer when the team uses these three terms consistently, because each variant has its own minimum size, clear space rule, and breakpoint range.

How do I prevent the mark from being recolored incorrectly at runtime?

Ship a separate single-color version of each variant, never recolor the primary mark through CSS variables. Recoloring a full color mark at runtime tends to produce off-brand shades and unreadable marks on busy backgrounds, while a dedicated single-color asset keeps the behavior consistent.

What is the minimum click target size for a logo in a responsive layout?

The widely accepted minimum is 44 by 44 CSS pixels on touch devices, regardless of the visual size of the mark. The behavior spec should call this out, because the visual mark can be smaller than the click target, and the developer needs to know how much padding to add around the image.

How often should a responsive logo spec be reviewed?

A quarterly review is a good default for most teams, with a single named owner and a small change log at the top of the document. The review should answer three questions, no more: does the spec match the assets, do the breakpoints match the product, and has the brand owner approved the latest changes.

Related reading

• Motion array basics: what it is and how creators use it
• Visual identity: what it is, what it includes, and how to build one