Crayons is the open-source web component library Freshworks uses for its own UI. Marketplace apps that adopt Crayons feel native. Apps that ship custom CSS feel like uninvited guests.
Why use Crayons
- Visual parity with the host product
- Dark mode and accessibility out of the box
- Faster review cycles (reviewers know the components)
- Token-based theming that auto-adapts to product updates
Install and import
Crayons ships as a web-components package. In a Marketplace app, you import the bundle in your manifest.
// app/template.html
<script type="module" src="https://unpkg.com/@freshworks/crayons@5/dist/crayons.esm.js"></script>
<fw-button color="primary">Save</fw-button>
<fw-input label="Customer email" required></fw-input>Use the layout primitives
Avoid hand-rolling flex/grid CSS. Crayons offers fw-stack, fw-cluster, and fw-data-table that match host product spacing tokens. Custom layouts will look 4 pixels off in dark mode.
Form patterns
The recommended form pattern uses fw-form with declarative validation. It handles error display, focus management, and submission events for you.
const form = document.querySelector("fw-form");
form.addEventListener("fwFormValuesChanged", (e) => {
// values map; native validation already done
});Theming and tokens
Do not override Crayons CSS variables in your app. Reviewers flag any --fw-color-primary redefinition. If you need a custom color, use a content-only style scoped to your component class.
Accessibility
Crayons components include ARIA roles, keyboard navigation, and focus rings by default. Custom components must replicate this; reviewers test with keyboard-only navigation.
Versioning
Pin to a major version (@5) and watch changelogs for breaking renames. Crayons does not auto-update inside your Marketplace app bundle.
What to do this week
Replace one custom-styled button or modal in your app with the Crayons equivalent, audit your CSS for --fw-* overrides, and test your app with keyboard-only navigation.
