--- title: "Colour Contrast in WordPress Blocks: A Repeatable Test" date: 2026-03-13 author: "Imtiaz Rayhan" featured_image: "https://wpblocksuite.com/wp-content/uploads/2026/08/featured-colour-contrast-wordpress-blocks.png" categories: - name: "Block Editor" url: "/blog/category/block-editor.md" --- # Colour Contrast in WordPress Blocks: A Repeatable Test Measure the actual foreground and background colours rendered on the public WordPress page. Normal text needs 4.5:1 contrast for WCAG 2.2 Level AA. Large text and essential non-text interface parts generally need 3:1. Test every interaction state. ## Measure the rendered pair A theme palette lists available colours. It does not prove which colours meet. Blocks, patterns, overlays, images, and states combine those colours into actual pairs. Test the final public pair. Editor previews can use different styles. ## Know the normal-text threshold WCAG 2.2 Level AA requires at least 4.5:1 for normal text. This includes images of text unless an exception applies. Real text remains preferable. The [W3C contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) explains thresholds, exceptions, and measurement notes. ## Know the large-text threshold Large-scale text needs at least 3:1 contrast for Level AA. Large means 18 points regular or 14 points bold. Font metrics matter. Those sizes approximate 24 pixels and 18.5 pixels respectively under CSS conversion. ## Do not round passing ratios Contrast thresholds are exact. A computed 4.499:1 does not meet 4.5:1. Some tools display rounded results. Inspect their underlying precision when values sit near thresholds. Aim above minimums. Small rendering and design changes then carry less risk. ## Know the non-text threshold Essential interface parts and graphical objects generally need 3:1 against adjacent colours. The [W3C non-text contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) defines which visual information applies. Test control boundaries, icons, selected states, and meaningful chart elements. ## Distinguish text from interface parts A button label follows text contrast. Its necessary boundary can follow non-text contrast. An icon communicating the action also needs sufficient distinction. Decorative shapes may not. Test each essential element against its actual adjacent colour. ## Understand the logo exception Text inside a logo or brand name has no minimum text-contrast requirement. That exception does not cover the whole brand palette. Ordinary branded text still applies. A logo acting as a control still needs an understandable usable interaction. ## Understand incidental exceptions Pure decoration, invisible text, and incidental text inside significant pictures can be exempt. Inactive interface components also receive specific treatment. Do not label active controls inactive. Apply exceptions narrowly. Normal content rarely becomes incidental merely because contrast is poor. ## Inventory every text role List body text, headings, links, captions, metadata, labels, notices, and placeholders. Include footer text, breadcrumbs, pagination, cards, badges, and table cells. Repeated block roles can share samples. Unique backgrounds need separate measurements. ## Inventory every interaction state 1. Measure the default state. 2. Measure hover styling. 3. Measure keyboard focus styling. 4. Measure active styling. 5. Measure selected styling. 6. Measure visited links. 7. Review disabled controls appropriately. 8. Measure error and success states. A default pass cannot cover state changes. Theme selectors often replace both colours. ## Choose a reliable contrast calculator Use a calculator implementing the WCAG relative-luminance formula. Record its name and version. Browser developer tools can inspect computed colours. Dedicated tools can calculate ratios. Cross-check borderline results with another dependable tool. Do not trust visual judgment alone. ## Capture the foreground colour Inspect the rendered element and record its computed foreground colour. Do not copy only the palette token name. Cascading styles may override it. Check inherited colours and state selectors. The final computed value controls measurement. ## Capture the background colour Trace the visible background through transparent ancestors. The nearest CSS background may be transparent. Record the actual composite colour behind the text. Include overlays and parent backgrounds. If no background is specified, WCAG evaluation assumes white for this criterion. ## Handle alpha transparency Semi-transparent foregrounds and backgrounds create composite colours. Raw hex values become misleading. Use a tool that resolves alpha against the real backdrop. Record the composite pair. Test every background where that transparent element appears. One token can produce several ratios. ## Handle gradients A [gradient presents](https://wpblocksuite.com/blog/wordpress-gradients-duotone/) many backgrounds beneath one text element. Contrast changes across its width. Measure the weakest relevant area. Text must remain readable across every occupied point. Add a solid overlay or text backing when necessary. Random placement increases risk. ## Handle background images Photographs contain changing luminance. One sample cannot represent the entire text area. Test darkest and lightest relevant regions. Responsive cropping can move those regions. Use a dependable overlay, shadow, or solid panel. Shadows alone need careful evidence. ## Handle Cover blocks Cover blocks combine media, overlay colour, opacity, and inner text styles. Measure the public crop at every breakpoint. Focal points can change the background. Check headings, paragraphs, links, and buttons separately. Their colours may differ. ## Handle duotone filters Duotone changes media appearance without changing stored image pixels. Overlaid text still needs testing. Inspect the rendered filtered result. Original-image samples cannot represent it. Retest after theme or filter changes. Preset names do not prove contrast. ## Test paragraph and heading blocks Measure body text against every section background. Include muted introductory and metadata styles. Check whether headings qualify as large text using actual size and weight. Do not assume every heading receives 3:1. Small headings still need 4.5:1. ## Test links in running text Link text needs sufficient contrast against its background. Identification also needs separate consideration. Measure default, visited, hover, and focus colours. Each state can fail independently. Underlines provide a useful non-colour cue. Do not rely on hue changes alone. ## Test Button blocks Measure button label against button background. Measure essential boundary against adjacent page colour. Repeat for hover, focus, active, and disabled appearances. Outline styles need special care. A transparent button can cross changing backgrounds. Test every placement. ## Test form blocks Measure labels, input text, placeholder text, instructions, errors, and success messages. Placeholder text is still text under contrast requirements. It cannot replace a label. Input boundaries and selected states may need non-text contrast. Test browser autofill too. ## Test focus indicators Focus must remain visible. Its essential visual indicator needs distinguishable contrast. Test outlines against button fills, cards, images, dark sections, and white sections. Two-colour focus rings can support varied backgrounds. Measure the relevant adjacent relationships. ## Test navigation blocks Measure desktop links, mobile links, submenu links, toggles, and current-page states. Overlay menus can use another background. Do not reuse desktop evidence. Icons and disclosure arrows may communicate essential states. Include their contrast. ## Test table blocks Measure header cells, data cells, captions, links, borders, and striped rows. Alternating backgrounds create several pairs. Every text colour needs each relevant measurement. Cell borders may convey relationships. Test them when spacing alone does not separate cells. ## Test notices and badges Badges often use small text and saturated backgrounds. They commonly need 4.5:1. Success and error colours must not carry meaning alone. Add text or icons. Measure icon and label separately. Their thresholds can follow different criteria. ## Test charts and diagrams Meaningful lines, bars, markers, and boundaries need adequate adjacent contrast. Colour differences alone cannot distinguish series. Add labels, patterns, or shapes. Provide equivalent data or explanation. Contrast does not make complex graphics fully accessible. ## Check thin and unusual fonts Underlying CSS colours determine formal measurement. Anti-aliasing can still make thin fonts appear weaker. W3C recommends stronger fonts or extra contrast where practical readability suffers. Passing mathematics cannot excuse unreadable typography. Test with real readers when possible. ## Record every measurement 1. Record the page and block. 2. Name the text or component. 3. Name the interaction state. 4. Record foreground colour. 5. Record background colour. 6. Record font size and weight. 7. Record calculated ratio. 8. Record required threshold. 9. Mark pass or failure. 10. Assign the correction owner. This evidence turns subjective debate into a reproducible result. Keep borderline precision. ## Fix the correct design layer A global token failure belongs in theme settings or `[theme.json](https://wpblocksuite.com/blog/what-is-theme-json-wordpress/)` where possible. A one-off block override can receive a local correction. Document why it differs. Fixing only one page leaves repeating failures elsewhere. Search for every affected use. ## Change one side deliberately Adjust foreground, background, overlay, or typography according to the [design system](https://wpblocksuite.com/blog/reusable-wordpress-design-system/). Do not darken every colour automatically. Preserve hierarchy and state distinction. Recalculate after each correction. Intuition cannot confirm the new result. ## Retest all affected states A corrected default colour can break hover or visited styling. Repeat the full state set. Check every background using the same token. Include responsive and dark-mode variants. Validate production after caches clear. Compiled CSS may differ from staging. ## Automate repeatable pairs carefully Automated scanners can find many CSS-based failures. They cannot sample every image background reliably. Use automation for broad regression coverage. Keep manual checks for dynamic visual cases. Review false positives and unsupported states. Tools provide evidence, not final judgement. ## Trace nested Group backgrounds Nested Groups can set several backgrounds. Inner transparency reveals the nearest painted ancestor. Select the text element in developer tools. Trace backgrounds until the visible surface appears. Responsive styles may remove one layer. Repeat the trace at each breakpoint. ## Audit Global Styles changes Global Styles can change text, links, buttons, and element defaults across many templates. Preview representative blocks before saving. Then inspect the anonymous public output. A global correction can improve many failures. It can also create new ones. ## Audit palette token changes Theme tokens can appear across backgrounds, borders, text, and icons. Their roles may conflict. Map every token toward actual uses before changing it. One hex value can serve several purposes. Create role-specific tokens where reuse becomes unsafe. Name them by purpose. ## Test alternate colour schemes Dark modes and high-contrast variants need independent measurements. Inversion rarely preserves every pair. Test system preference changes and manual toggles. Include saved and initial states. Verify icons, charts, focus, and images too. Text passes are insufficient. ## Test selected and highlighted text Custom selection colours can make selected text unreadable. Test representative sections. Inline highlights create another foreground and background pair. Measure every highlight preset. Do not use highlighting only for meaning. Provide structural or textual cues. ## Test pagination and query controls Current pages, disabled arrows, hover states, and focus states use different colours. Measure labels and essential boundaries. Small controls remain normal-sized text unless proven otherwise. Test [Query Loop](https://wpblocksuite.com/blog/wordpress-query-loop-block/) variations and archive templates. Global pagination styles may differ. ## Test SVG icons SVG fills and strokes can inherit current colour or use fixed values. Inspect the rendered property. Test meaningful lines against every adjacent surface. Decorative icons may be exempt from information requirements. Control icons usually are not. ## Test captions and footnotes Captions and footnotes often use smaller muted text. They still carry important information. Measure them using the normal-text threshold unless their actual typography qualifies otherwise. Include backlink icons and focus states. Small details can become complete barriers. ## Treat editor warnings as prompts The editor may warn about certain colour combinations. Use that warning as a starting point. It cannot evaluate every rendered background, overlay, state, or plugin stylesheet. Measure the public page anyway. Automated editor guidance provides incomplete evidence. ## Create a contrast ownership map Record which theme token, block setting, plugin style, or custom rule owns each pair. Assign corrections toward the most reusable layer. Avoid scattered emergency overrides. Review ownership after theme switches. Old assumptions can survive inside content attributes. ## Know what contrast cannot solve Passing contrast cannot repair tiny text, cramped spacing, or confusing hierarchy. It cannot replace colour-independent meaning. It also cannot guarantee comfortable reading. This is the honest weak case. Treat ratios as minimum evidence within broader design quality. ## Use the contrast test checklist 1. Open the anonymous public page. 2. Inventory every visual role. 3. Inventory every interaction state. 4. Inspect computed foreground colour. 5. Resolve the actual background. 6. Handle transparency and overlays. 7. Calculate without rounding. 8. Apply the correct threshold. 9. Test gradients and images. 10. Test text and interface parts. 11. Record exact evidence. 12. Fix the owning design layer. 13. Retest every affected state. 14. Verify production output. ## Frequently asked questions What contrast ratio does normal WordPress text need? WCAG 2.2 Level AA requires at least 4.5:1 for normal text. What ratio does large text need? Large-scale text needs at least 3:1 for Level AA. Can I round a 4.499 ratio to 4.5? No. WCAG treats contrast ratios as exact thresholds without rounding. Does a passing theme palette prove block contrast? No. Measure the actual rendered foreground, background, placement, and state. Do logos need 4.5 to 1 contrast? Logo and brand-name text receive a specific contrast exception. ## The verdict Verdict **Measure actual pairs:** palette names cannot prove rendered contrast across backgrounds and states. **Keep evidence:** record exact colours, ratios, thresholds, locations, states, and verified corrections. Core colour controls can create passing or failing pairs. Test every combination. Then [compare the $299 lifetime suite](https://wpblocksuite.com/#pricing) when several Pro blocks pass your contrast audit.