How I gave Claude our entire design system in a single file

I've been experimenting with skills lately, trying to give Claude a reliable reference model for our design system at work. I wanted Claude to know exactly what I mean when I say "use the main nav component" - working from our actual codebase, not inferring from general patterns.

Skills have a hard limit though - 200 files and 30MB uncompressed. Our React design system spans well beyond that, so I needed another approach.

That's where JSONL came in.

What I was trying to do

I want to be clear about the distinction here, because it matters. I didn't want Claude to produce something that looks like our components. I wanted it to work from the real implementation - the actual source code, not a reconstruction based on what navigation components typically look like.

There's a meaningful difference between an LLM making educated guesses versus having the literal source in front of it. The first is useful generally. The second is what you need when you're building on top of a system that real users depend on.

What is JSONL?

JSONL - JSON Lines - is a file format where each line is its own complete, self-contained JSON object. No wrapping array, no shared root, no commas between records. Just a stream of structured entries, one per line.

The mental model that works for me: think of it like a stack of index cards. Each card is a complete record. You can add one without touching the others, and you can read one without loading the rest. Critically, you can pack an enormous amount of structured information into a single file, with none of the multi-file constraints that skills impose.

It's also worth knowing this is essentially the default format for AI and ML work. OpenAI fine-tuning, Anthropic batch processing, Hugging Face datasets - they all consume or produce JSONL. The pattern is consistent: one line equals one example, one request, one record.

Getting the design system into that format

I gave Claude Cowork access to our design system source code and asked it to help convert everything into JSONL. This is where things got interesting.

We use Storybook alongside our component library. Storybook stores its content in <component>.stories.js files, sitting right next to the actual component code. That turned out to be a happy coincidence - it meant I could pull in both the implementation and the human-readable documentation in a single pass. The story file tells you what the component does, what props it accepts, what the intended use cases are. The component file tells you exactly how it works.

Each component ends up as its own record in the JSONL, sitting right alongside its Storybook documentation. The source code and the human-readable context are separate lines, but they're all in the same file. When Claude reads it, it gets both.

How it's working in practice

The end result is a single file containing every component in the system - source code, Storybook documentation, prop definitions, usage patterns.

When I reference the "main nav component" now, Claude isn't guessing. It has the real implementation and can reason about how props compose, what the constraints are, and how the component relates to the rest of the system. Not reconstructed. Not approximated.

It's working remarkably well.

What this doesn't solve

A React-based design system still needs a proper environment to run. You can't hand Claude a JSONL file and get fully functional, renderable component code in isolation - there's infrastructure, build tooling, and runtime context that live outside the file. That's a different layer of the problem, and I'll write about it separately.

JSONL solves is the knowledge gap. Claude now has an accurate reference model for our design language. It knows what our components actually are, not what components in general tend to look like.