Forem: Cüneyt Çakar

Building Spexop: A Journey in Design System Development

Cüneyt Çakar — Wed, 05 Nov 2025 11:10:38 +0000

Hey there.

I wanted to share a bit about building Spexop, a design system that started as a personal project and has slowly grown into something I'm actually pretty happy with. This isn't a "how we built the perfect design system" post—more like a casual reflection on what I've learned along the way.

The Beginning

It started with my desire to build my own design system instead of trying to be an expert on existing ones. I was working on sensitive applications, and I needed something I could understand completely, control fully, and trust implicitly. Existing design systems were great, but they were someone else's vision—someone else's decisions about what mattered and what didn't.

I found myself reaching for the same patterns over and over again. Grid layouts, buttons, forms, cards—you know the drill. After the third or fourth time copy-pasting the same component code, I thought, "maybe I should just make a library for this."

So I did. I started with the basics: a Grid component, a Button, a Card. Nothing revolutionary, just components that worked the way I wanted them to work. I wrapped them up in a package, published it to npm, and called it a day.

Except it wasn't really a day. It was more like the start of something that would occupy way more of my time than I initially planned. But building my own design system meant I could understand every line of code, every design decision, every trade-off. And for the sensitive applications I was working on, that control mattered.

The Philosophy Shift

Early on, I realized that if I was going to build a design system, I should probably have some guiding principles. I didn't want to just create another component library that looked nice but didn't really help developers think differently about building interfaces.

So I started thinking about what mattered to me:

Primitives before patterns - Master the grid system first, then build complex things
Borders before shadows - Clean, minimal aesthetics with strong borders instead of heavy shadows
Typography before decoration - Use font weight for hierarchy, not lighter colors
Tokens before magic numbers - Everything should use design tokens
Composition before complexity - Build up from simple parts
Standards before frameworks - Use web platform fundamentals
Accessibility before aesthetics - WCAG AA+ compliance by default

These seven principles became "The Spexop Way." It sounds a bit pretentious when I type it out, but honestly, it's just the way I think about building things. And it's helped me make decisions when I'm not sure which direction to go.

The Component Library

Fast forward a bit, and I've got 60+ components. That number still surprises me when I write it down. It started with five grid primitives (Grid, GridItem, Stack, Container, Spacer), and then I just kept adding things as I needed them.

Navigation components came next—TopBar, Sidebar, Navigation. Then forms, buttons, cards, overlays. Each time I built something for a project, I'd think, "this could be useful for others too," and I'd add it to the library.

The interesting part, at least to me, is how the structure evolved. I started with a flat list of components, but that didn't scale well. Now components are organized by category: primitives, navigation, forms, buttons, cards, layout, overlays, display, settings, advanced, and animations.

The Theme System

The theme system was probably the most challenging part to get right. I wanted something that was flexible but not overly complex. I tried a few different approaches before landing on what we have now.

The current system uses CSS custom properties (CSS variables) for everything. You can define a theme as a JavaScript object, and it gets converted to CSS variables that components consume. It's simple, performant, and works with any CSS framework.

I've included 13 pre-built themes (tech, startup, healthcare, finance, ecommerce, etc.), but you can easily create your own. The theme generator can export to 29+ different formats, which is probably overkill, but it's useful when you need to integrate with different tools.

Going Provider-Free

One of the bigger architectural decisions was moving away from React Context providers. I know, I know—everyone uses providers. But I wanted something simpler, something that didn't require wrapping your entire app in multiple provider components.

So I built utility hooks instead. useToastUtil, useModalUtil, useThemeUtil, etc. They work standalone, without providers. You just call the hook and use it. It's a bit different from what most React developers are used to, but I think it's cleaner.

The migration from providers to utilities was a bit of a pain, but I think it was worth it. The API is simpler, and there's less boilerplate. Plus, you can use these utilities anywhere in your app without worrying about provider hierarchy.

The Icons Package

I didn't plan on building an icons package initially. But I needed icons for the components, and I didn't want to force people to use a specific icon library. So I created @spexop/icons with 269 icons.

It's not the biggest icon library out there, but it covers the basics well. Each icon has a filled variant, and I've included some brand icons too. They're all SVG-based, tree-shakeable, and fully typed.

The CLI

At some point, I realized that getting started with Spexop could be easier. So I built a CLI tool that scaffolds new projects. You can run npx @spexop/cli create my-app and get a fully set up project in seconds.

It's not a huge feature, but it removes friction. And removing friction is one of those small things that can make a big difference in developer experience.

Developer Tools

I've also been working on some developer tools around Spexop. There's a VSCode extension (still at version 0.0.1, so it's early days) that provides code snippets and IntelliSense for Spexop components. It's available on the VSCode Marketplace, but it's still a work in progress.

I'm also building an MCP (Model Context Protocol) server for Spexop, though it's not published yet. The idea is to make it easier for AI assistants to understand and work with Spexop components. It's one of those side projects that might be useful, or might just be me overthinking things. We'll see.

Speaking of AI assistants, I've been working with them quite a bit for haste. They're great for getting things done faster, especially when you're building something as large as a design system. I can focus on the big decisions and architecture while letting AI handle some of the repetitive work. It's been a game changer for productivity, honestly.

What I've Learned

Building a design system is harder than I thought it would be. Not because the code is complex (though some of it is), but because of all the decisions you have to make. Every API choice matters. Every naming convention matters. Every breaking change affects real people using your library.

I've made mistakes. I've deprecated features. I've changed APIs. I've broken things and had to fix them. And I've learned that's okay. It's part of the process.

The most important thing I've learned is to listen to feedback. When people report bugs or suggest features, I try to understand what they're really trying to accomplish. Sometimes the answer isn't adding a new component—it's fixing an existing one or improving the documentation.

The Community

I'm grateful for everyone who's tried Spexop, reported bugs, suggested improvements, or just said "hey, this is cool." Building something in public is weird sometimes, but it's also really rewarding.

I don't have a huge community yet, but the people who do use Spexop seem to genuinely like it. That's enough for me.

What's Next

I'm not entirely sure, to be honest. I'm still actively developing Spexop, adding components, fixing bugs, improving the documentation. There are always things to improve.

I'd like to add more components, refine the API, improve the documentation. Maybe build a visual theme builder (I've started on this, but it's not ready yet). Maybe add React Native support (there's already a basic package, but it needs work).

But mostly, I just want to keep building things that are useful. That's the goal, really. Build useful things, and if other people find them useful too, that's a bonus.

Final Thoughts

Building Spexop has been a journey. It's taken more time than I expected, but I've learned a lot along the way. I've made something I'm proud of, even if it's not perfect.

If you're thinking about building a design system, my advice would be: start small, iterate often, and don't be afraid to change things. Also, document everything. Future you will thank present you.

If you want to check out Spexop, you can find it at spexop.com. The docs are at docs.spexop.com, and the code is on GitHub.

Thanks for reading. If you have questions or feedback, feel free to reach out. I'm always happy to chat about design systems, React, or really anything development-related.

Spexop Design System - Built with TypeScript & React (for now)

Website • Docs • GitHub • npm

@spexop/react v0.3.1: Building with Primitives-First Philosophy

Cüneyt Çakar — Tue, 21 Oct 2025 15:11:13 +0000

---
title: "@spexop/react v0.3.1: Building with Primitives-First Philosophy"
published: true
tags: react, typescript, webdev, opensource
---

# @spexop/react v0.3.1: Building with Primitives-First Philosophy

I'm excited to share the latest release of @spexop/react - a React component library that emphasizes mastering fundamentals before building complexity.

## The Primitives-First Approach

Instead of jumping straight to complex components, Spexop encourages starting with 5 grid primitives:
- Grid
- GridItem
- Stack
- Container
- Spacer

Master these, then compose them into sophisticated interfaces. This leads to more maintainable code and better design consistency.

## What's New in v0.3.1

### 13 New Components

**Data Components**

tsx
import { DataTable } from '@spexop/react';

columns={columns}
data={data}
sortable
filterable
pagination
/>


- **Feedback Components**

tsx
import { Alert, Spinner, Progress } from '@spexop/react';

Operation successful!


- **Typography Components**

tsx
import { Heading, Text, Link } from '@spexop/react';

Page Title
Body text
Documentation


### 33+ React Hooks

20+ new hooks for common patterns:

tsx
// Storage
const [value, setValue] = useLocalStorage('key', defaultValue);

// Browser APIs
const isOnline = useOnline();
const size = useWindowSize();

// Interaction
const ref = useClickOutside(() => setIsOpen(false));

// Utilities
const debouncedValue = useDebounce(value, 500);
const [copied, copy] = useCopyToClipboard();


### 100% Documentation

Every component (all 59!) now includes:

- Comprehensive README
- USAGE-GUIDE with practical examples
- Component tests
- TypeScript definitions

## The Design Philosophy

Spexop follows 7 core principles:

1. **Primitives before patterns** - Master the grid first
2. **Borders before shadows** - Clean 2px borders, not heavy shadows
3. **Typography before decoration** - Use font weight for hierarchy
4. **Tokens before magic numbers** - Design system consistency
5. **Composition before complexity** - Build from simple parts
6. **Standards before frameworks** - Web fundamentals
7. **Accessibility before aesthetics** - WCAG AA+ compliance

## Enhanced Components

### Carousel

Full-featured slideshow with:

- Touch/swipe support
- Keyboard navigation
- Thumbnails
- Auto-play
- Lazy loading

### CodeBlock v3

Redesigned with:

- Custom syntax highlighting
- Multi-framework support (React, Vue, Angular)
- Theme integration
- Performance optimizations

## Installation

bash
npm install @spexop/react@0.3.1 @spexop/theme @spexop/icons


## Breaking Changes in v0.3.1

Animation imports changed:

tsx
// ❌ Old
import { FadeIn } from '@spexop/react/animations';

// ✅ New
import { FadeIn } from '@spexop/react';


See [Migration Guide](https://github.com/spexop-ui/spexop-design-system/blob/main/packages/react/MIGRATION-GUIDE.md) for details.

## Development Status

This is an active development release. While components follow design principles and include comprehensive documentation, the library is still evolving.

## Links in v0.3.1

- npm: <https://www.npmjs.com/package/@spexop/react>
- GitHub: <https://github.com/spexop-ui/spexop-design-system>
- Documentation: <https://spexop.com>

Feedback and contributions welcome! 🙌

bash

Introducing @spexop/icons: A Modern React Icon Library with 262 Professional Icons

Cüneyt Çakar — Thu, 09 Oct 2025 18:05:48 +0000

Introducing @spexop/icons: A Modern React Icon Library

I'm excited to share @spexop/icons - a professional icon library built specifically for modern React applications.

🎯 Why Another Icon Library?

Fair question! While there are many excellent icon libraries out there, I found myself repeatedly running into the same issues:

Bundle size concerns: Importing entire libraries for just a handful of icons
Missing variants: Needing both outlined and filled versions of icons
Scattered dependencies: Installing separate packages for brand/social icons
TypeScript friction: Poor or missing type definitions
Accessibility gaps: Having to manually add ARIA attributes

@spexop/icons addresses all of these pain points.

✨ Key Features

1. Comprehensive Icon Collection

262 carefully curated icons across 20+ categories:

Navigation & Arrows (27)
Actions & Editing (14)
Communication (11)
Media & Entertainment (14)
Files & Folders (13)
Social & Community (15)
Weather (8)
Development Tools (10)
System & Status (20)
...and more!

2. Filled Variants Built-In

No need for separate packages! Includes filled versions of commonly used icons:

import { Heart, HeartFilled, Star, StarFilled, Bookmark, BookmarkFilled } from '@spexop/icons';

// Mix and match based on state
const [liked, setLiked] = useState(false);

<button onClick={() => setLiked(!liked)}>
  {liked ? <HeartFilled color="#ef4444" /> : <Heart />}
</button>

3. Brand Icons Included

30+ popular brand and social media icons:

Facebook, Twitter/X, Instagram, LinkedIn
GitHub, GitLab, Discord, Slack
Apple, Google, Microsoft
And many more!

No need for react-icons just for brand logos.

4. Tree-Shakeable by Design

Only pay for what you use:

// This adds ~0.5KB to your bundle
import { Home, Settings } from '@spexop/icons';

// Not this entire library
import * as Icons from '@spexop/icons'; // ❌ Don't do this

Built with modern bundlers in mind (Vite, Webpack 5+, Rollup).

5. Fully Typed with TypeScript

Strict TypeScript support with full IntelliSense:

import { IconProps } from '@spexop/icons';

interface IconProps extends React.SVGProps<SVGSVGElement> {
  size?: number | string;
  color?: string;
  title?: string;
  className?: string;
  strokeWidth?: number;
}

6. Accessible by Default

Every icon includes proper ARIA attributes:

<Search title="Search" />
// Renders with role="img" and aria-label="Search"

📦 Installation

# Using pnpm
pnpm add @spexop/icons

# Using npm
npm install @spexop/icons

# Using yarn
yarn add @spexop/icons

🚀 Quick Start

Basic Usage

import { Home, User, Settings, Bell } from '@spexop/icons';

function App() {
  return (
    <nav>
      <Home />
      <User size={32} />
      <Settings color="#3b82f6" />
      <Bell strokeWidth={1.5} />
    </nav>
  );
}

Customization

Icons inherit color from CSS by default:

<div style={{ color: '#ef4444' }}>
  <Home /> {/* Will be red */}
</div>

Or customize directly:

<Settings 
  size={24}
  color="#3b82f6"
  strokeWidth={2}
  className="icon-rotate"
  title="Application Settings"
/>

With Tailwind CSS

<Home className="w-6 h-6 text-blue-500 hover:text-blue-700" />

Dynamic Icons

const iconMap = {
  home: Home,
  settings: Settings,
  user: User,
};

function DynamicIcon({ name }: { name: keyof typeof iconMap }) {
  const Icon = iconMap[name];
  return <Icon />;
}

🎨 Design Philosophy

All icons follow consistent design principles:

24×24 pixel base size: Scales perfectly at any size
2px stroke width: Clean and readable
Minimal style: Works with any design system
Optimized SVGs: Automatically processed with SVGO
No hardcoded colors: Fully customizable

📊 Bundle Size

One of the biggest advantages is the minimal bundle impact:

Import Style	Bundle Impact
Single icon	~0.5KB
10 icons	~5KB
Entire library (don't!)	~57KB
Gzipped	~17KB

Compare this to libraries that force you to import everything!

🛠️ Technical Details

Build Output

ESM: Modern import syntax
CJS: Legacy require() support
TypeScript: Full .d.ts definitions
Source maps: Included for debugging

Zero Dependencies

The published package has zero runtime dependencies. Only peer dependency:

{
  "peerDependencies": {
    "react": ">=16.8.0"
  }
}

Works with React 16.8+ (Hooks era) through React 19.

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

📚 Documentation

Comprehensive documentation available:

Icon Catalog: Browse all 262 icons with search
API Reference: Complete props documentation
Examples: Real-world usage patterns
Contributing Guide: Add your own icons
TypeScript Guide: Advanced type usage

🤝 Contributing

This is an open-source project and contributions are welcome!

Ways to contribute:

Request new icons
Submit icon designs (SVG files)
Improve documentation
Report bugs
Share feedback

Check out the Contributing Guide.

🗺️ Roadmap

Plans for future releases:

v0.2.0: Animated icon variants
v0.3.0: Additional size presets (16px, 20px, 32px)
v1.0.0: Stable API, 300+ icons
Vue & Svelte versions (community request)

🎓 Lessons Learned

Building this library taught me:

SVG optimization matters: SVGO reduced file sizes by 40%
Tree-shaking isn't automatic: Proper ESM structure is crucial
TypeScript strict mode catches bugs: Saved hours of debugging
Documentation is half the work: Good docs = happy users
Testing in real projects: Dogfooding reveals issues fast

🔗 Links

npm: npmjs.com/package/@spexop/icons
GitHub: github.com/spexop-ui/icons
Icon Catalog: View all 262 icons
Issues: Report bugs or request features

💬 Feedback Welcome!

This is the first release, and I'd love to hear your thoughts:

What icons are missing?
What features would you like?
How can we improve the DX?

Drop a comment below or open an issue on GitHub!

Try It Out!

npm install @spexop/icons

import { Home, Heart, Github } from '@spexop/icons';

function App() {
  return (
    <div>
      <Home size={32} color="#667eea" />
      <Heart color="#ef4444" />
      <Github size={24} />
    </div>
  );
}

Happy coding! 🚀

Built by Spexop UI

Cuneyt Cakar (@olmstedian)

📧 ccakar@spexop.com

🌐 www.spexop.com

If you found this useful, give it a ❤️ and share with your network!