Mafunzo ya Open Claude UI: Jenga kiolesura cha mazungumzo ya AI chenye uaminifu wa juu na uhuishaji wa mwingiliano wa kiwango cha uzalishaji

Utangulizi wa mradi

open-claude-ui ni maktaba huria ya vipengele vya UI na injini ya uhuishaji kwa programu za kisasa za AI za kompyuta za mezani. Mradi huu unatumia mfumo wa uhandisi wa kubadili REA kufanya uchanganuzi tuli wa AST, kuondoa uchanganyaji wa msimbo wa closures, kufuatilia wakati wa utekelezaji na kuchanganua rasilimali za ASAR, kisha kupanga matokeo ya utafiti kuwa vipengele vya React vinavyoweza kutumika tena, Hooks, mitindo ya mandhari na nyaraka za kiufundi.

Si nakala ya mwonekano wa kiolesura pekee, bali pia hurejesha mifumo ya kihandisi inayoathiri ubora wa mwingiliano, kama vile vigezo vya spring za kifizikia, ulinzi wa mbinu za kuingiza CJK, kufifia kwa kingo za kusogeza, udhibiti wa usogezaji wa ujumbe wa mtiririko, ukuzaji uliotiwa nanga kwenye kishale, eneo lisilohesabiwa wakati wa kuburuta na sauti za arifa zinazozalishwa kwa Web Audio.

Maelezo ya uzingatiaji: Mradi hausambazi rasilimali za binary za umiliki kama fonti za kibiashara na faili za rekodi, bali hutumia mfululizo wa fonti za mfumo na athari za sauti za msimbo kupitia Web Audio API. Mradi umetolewa chini ya MIT License, na matokeo yanayohusiana yanakusudiwa kujifunza, kufanya utafiti na kubadilishana maarifa ya kihandisi.

Inafaa kwa miradi gani

Ikiwa unatengeneza programu ya mazungumzo ya AI, dashibodi ya modeli, kiolesura cha kuidhinisha miito ya zana, msaidizi wa kompyuta ya mezani, kitazamaji cha media au nafasi ya ushirikiano wa mawakala wengi, unaweza kuingiza vipengele kutoka kwenye hazina hii kulingana na mahitaji, bila kulazimika kurekebisha mwenyewe tokeni za kuona na mwingiliano changamano.

• Programu za AI za wavuti: Tumia viputo vya mazungumzo, kisanduku cha kuingiza maandishi yenye umbizo, kiteuzi cha modeli na dashibodi ya Token.
• Kiolesura cha uzalishaji wa mtiririko: Tumia pini ya kusogeza, kukunja mchakato wa kufikiri na kifuniko cha kufifia.
• Programu za kompyuta za mezani: Tumia kiunda madirisha cha Electron, upau wa kichwa wa macOS na mpangilio wa nyenzo wa Vibrancy.
• Programu za Artifacts na media nyingi: Tumia kuburuta kwa mpangilio wa safu, lightbox ya media, mpito wa vipengele vinavyoshirikiwa na daraja la sandbox la iframe.
• Programu zinazofikika: Tumia Hook ya Roving TabIndex ya kuzunguka fokusasi, inayofuata kanuni za WAI-ARIA.

Vipengele muhimu

Tokeni za muundo na mfumo wa kuona

Mradi hutoa ngazi ya nyuso zenye utofauti mdogo kutoka Surface 0 hadi Surface 3, rangi ya udongo wa matofali #d97757, marekebisho ya mipaka myembamba kwa skrini zenye msongamano mkubwa wa pikseli, mfululizo wa fonti za mfumo, pamoja na matriki ya pembe zilizozungushwa kwa vitufe, paneli, viputo na visanduku vya kuingiza. Vigezo vya mandhari ya kimataifa na keyframes muhimu vimewekwa pamoja katika code-examples/cds-theme.css.

Moduli 30 huru za msimbo

Hazina hii ina vidhibiti 11 vya msingi vya atomiki na moduli 19 za usanifu au mwingiliano. Msimbo wa vipengele uko katika code-examples, na sehemu ya pamoja ya kuingiza ya TypeScript iko katika src/index.ts. Moduli hizi hushughulikia vitufe, chaguo la sehemu, visanduku vya kuingiza, viputo vya mazungumzo, kadi za maamuzi za MCP, vitazamaji vya media, Diff ya mtiririko, madirisha ya kompyuta ya mezani na turubai za mawakala wengi.

Mifumo ya mwingiliano ya kiwango cha uzalishaji

• Seti 4 za mipangilio ya spring za kifizikia, zikiwemo Bouncy, Snappy, Gentle na Heavy Snap.
• Maeneo ya kusogeza hutumia vifuniko 7 vya Alpha visivyo vya mstari, vinavyorekebishwa kulingana na iwapo eneo limefika juu au chini.
• Visanduku vya kuingiza hulinda mbinu za CJK kwa masharti mawili ya isComposing na keyCode === 229.
• Matokeo ya mtiririko hutumia ustahimilivu wa chini wa 40px na muda wa kusubiri wa 150ms baada ya kusogeza kwa mkono, ili usogezaji wa kiotomatiki usichukue mwonekano.
• Mawimbi ya maikrofoni hutumia kizingiti cha kelele cha 8% na ukandamizaji wa Gamma wa nguvu 0.7.
• Mwingiliano wa kuburuta na ghala huongeza eneo lisilohesabiwa la 4px la mwendo wa pointeri ili kuchuja mitikisiko midogo ya mkono.

Hakiki ya vipengele nje ya mtandao

Hazina hii inajumuisha storybook ya mwingiliano ya faili moja katika docs/claude-components-storybook.html. Hakuna haja ya kuanzisha seva ya maendeleo ya ndani ili kuona mfumo wa rangi za udongo wa matofali, hali nyeusi, mrejesho wa vitufe, vidonge vya sehemu, uhuishaji wa spring, vigae vya viambatisho na uhuishaji wa hali ya kunakili.

Usakinishaji na maandalizi ya mazingira

Thibitisha teknolojia zinazotumika

Kulingana na maelezo ya hazina, inashauriwa mradi uwe na mazingira yafuatayo:

• React 18 au toleo jipya zaidi.
• TypeScript 5.5 au toleo jipya zaidi.
• Tailwind CSS 3.4 au toleo jipya zaidi.
• Framer Motion 11 au toleo jipya zaidi.

README haitoi amri maalum ya usakinishaji kwa kidhibiti fulani cha vifurushi. Kabla ya kuanza, kulingana na workspace yako, utegemezi wa Git au njia ya kuchapisha kifurushi, hakikisha mradi unaweza kufikia njia ya open-claude-ui na kwamba teknolojia zote zilizotajwa hapo juu zimesanidiwa.

Angalia storybook ya nje ya mtandao kwanza

Ikiwa tayari umepata msimbo wa chanzo wa hazina, unaweza kufungua faili ya hakiki moja kwa moja:

open docs/claude-components-storybook.html

Bila kubadilisha mradi wa biashara, hatua hii hukusaidia kuthibitisha iwapo mwonekano wa vipengele, mandhari nyeusi na uhuishaji wa mwingiliano vinakidhi mahitaji ya mradi.

Sanidi mitindo ya mandhari

Ingiza CSS ya kimataifa

Ingiza faili ya mandhari ya CDS katika sehemu ya kuingiza mitindo ya kimataifa ya programu. Ina sifa maalum za CSS na keyframes zinazohitajika na vipengele:

@import "open-claude-ui/code-examples/cds-theme.css";

Mandhari hii hutoa rangi za nyuso, rangi ya chapa ya udongo wa matofali, mipaka, vivuli na misingi ya uhuishaji. Ili kudumisha uthabiti kati ya vipengele, inashauriwa kutumia vigezo vya CSS vilivyopo badala ya kuweka rangi kwa thamani zisizobadilika katika kila kipengele.

Panua usanidi wa Tailwind

Katika tailwind.config.js ya mradi, pakia upanuzi wa mandhari uliotolewa na hazina:

const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      ...cdsTheme.theme.extend
    }
  }
};

Safu ya content inapaswa kujumuisha msimbo wa chanzo wa programu yako pamoja na faili zilizo katika open-claude-ui zenye majina ya madarasa ya Tailwind. Vinginevyo, wakati wa kujenga toleo la uzalishaji, huenda utility classes zinazotumiwa na vipengele zisitengenezwe.

Matumizi ya msingi: Jenga eneo la udhibiti wa modeli na kuingiza mazungumzo

Mfano ufuatao unaunganisha moduli tatu muhimu:

1. ScrollFadeContainer huongeza kufifia kwa kingo za juu na chini kwenye eneo linaloweza kusogezwa.
2. ModelSwitcherWithTokenGauge huonyesha uteuzi wa modeli, hali ya Extended Thinking na bajeti ya Token.
3. ChatComposer hutoa uingizaji wa ujumbe na callback ya kutuma.

import React, { useState } from 'react';
import {
  ChatComposer,
  ModelSwitcherWithTokenGauge,
  ScrollFadeContainer
} from 'open-claude-ui';

export function App() {
  const [model, setModel] = useState<
    'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
  >('sonnet-3.5');
  const [thinking, setThinking] = useState(true);

  return (
    <div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
      <ScrollFadeContainer
        axis="vertical"
        fadeSize={32}
        className="flex-1 p-6"
      >
        <div className="mx-auto max-w-3xl space-y-4">
          <ModelSwitcherWithTokenGauge
            currentModel={model}
            onModelChange={setModel}
            extendedThinking={thinking}
            onThinkingChange={setThinking}
            tokenBudget={{
              inputTokens: 12400,
              outputTokens: 3200,
              cacheReadTokens: 48000,
              cacheWriteTokens: 16000,
              maxContextWindow: 200000
            }}
          />

          <ChatComposer
            onSend={(text) => console.log('Send message:', text)}
          />
        </div>
      </ScrollFadeContainer>
    </div>
  );
}

Elewa usimamizi wa hali

currentModel na extendedThinking zote zinasimamiwa na safu ya programu, hivyo kiteuzi cha modeli kinaweza kusawazishwa na usanidi halisi wa ombi la modeli. tokenBudget katika mfano hupitisha tokeni za kuingiza, kutoa, kusoma akiba, kuandika akiba na dirisha la juu la muktadha kwa dashibodi.

ChatComposer ya onSend katika mfano huandika kumbukumbu pekee. Unapounganisha na mradi halisi, unaweza kuita huduma yako ya mazungumzo katika callback hii, kusasisha orodha ya ujumbe na kuanzisha hali ya mwitikio wa mtiririko.

Mwongozo wa kuchagua vipengele vinavyotumika mara nyingi

Vidhibiti vya msingi

• CdsButton: Hutoa saizi XS, SM, MD na LG, pamoja na aina Primary, Secondary, Ghost, Outline na Danger.
• SegmentedControl: Hutumika kubadilisha modi na inasaidia uwekaji wa kijiometri pekee pamoja na mpangilio wa uhuishaji wa Framer Motion layoutId.
• StatusIndicators: Inajumuisha mwanga wa kupumua wa udongo wa matofali, mpigo wa shughuli za wakati halisi, uhuishaji wa nukta tatu za kufikiri na mwanga wa kuscan wa skeleton.
• ConfirmationDialog: Hutumika kuthibitisha vitendo vya kawaida au hatari, ikiwa na kifuniko kilichofifishwa na kizuizi cha fokusasi ya kibodi.
• AttachmentCard: Inasaidia njia mbili za kuonyesha viambatisho: vigae vya kompyuta ya mezani na vidonge vya mstari ndani ya kisanduku cha kuingiza.

Majadiliano na miito ya zana

• ChatMessageBubbles: Hutofautisha viputo vya mtumiaji na mpangilio wa uwazi wa msaidizi.
• ThinkingAccordion: Huonyesha mchakato wa kufikiri unaoweza kukunjwa na inaweza kuufanya ubaki wazi wakati wa uzalishaji.
• RichComposerWithMentions: Inafaa kwa vituo vya kuingiza vinavyohitaji maagizo ya /, muktadha wa @ na utabiri wa Token.
• McpToolDecisionCard: Hutumika katika mchakato wa kuidhinisha zana na inashughulikia hali za pending_approval, running, success na error.

Media, msimbo na Artifacts

• MediaLightboxViewer: Hutoa njia ya ghala ya 75vw, Pan/Zoom iliyotiwa nanga kwenye kishale, eneo lisilohesabiwa la kuburuta na ukuzaji kwa gurudumu la Ctrl.
• ArtifactsSplitPaneResizer: Hushughulikia kubadilisha ukubwa wa safu mbili, kukunja kingo, kunasa kwa 50/50 kwa kubofya mara mbili na mwingiliano wa matukio ya pointeri ya iframe.
• EpitaxyIframeBridge: Huunganisha sandbox ya hakiki kupitia uthibitishaji wa Origin na itifaki ya RPC ya postMessage iliyotengwa.
• StreamingDiffViewer: Inasaidia kuongeza kwa mtiririko wa nyongeza pamoja na modi za Diff zilizounganishwa na za skrini iliyogawanywa.
• CodeBlock: Hutoa kontena la msimbo na kupungua kwa hali ya kunakili baada ya sekunde 2.5.

Mazoea ya juu

Kulinda mbinu za kuingiza za Kichina, Kijapani na Kikorea

Ikiwa kisanduku cha mazungumzo kinahitaji kupanua matukio ya kibodi, lazima uhifadhi ulinzi wa utungaji wa mbinu ya kuingiza. Mtumiaji anapobonyeza Enter akiwa kwenye dirisha la mapendekezo ya Pinyin au Kana, ujumbe haupaswi kutumwa. Mradi hutumia ukaguzi wa masharti mawili:

const composing =
  event.nativeEvent.isComposing || event.keyCode === 229;

if (event.key === 'Enter' && !composing) {
  // Tuma ujumbe
}

Kwa kitufe cha Escape, unapaswa pia kuzuia tukio kuendelea kupanda wakati wa kufunga safu ya mapendekezo ya mbinu ya kuingiza, ili lisifunge dirisha la mazungumzo bila kukusudia.

Kuzuia utiririshaji wa matokeo usichukue nafasi ya kusogeza

Unaweza kutumia useClaudeScrollPinning kudhibiti Token zinazoongezwa mfululizo. Mkakati wake mkuu unajumuisha ustahimilivu wa 40px chini, kipindi cha 150ms cha kupoza baada ya kusogeza kwa mkono, na akiba thabiti ya 35vh. Mtumiaji anapokuwa karibu na mwisho wa chini, kiolesura kinaweza kufuatilia matokeo; mtumiaji anapoanza kusogeza juu ili kuvinjari ujumbe wa awali, usogezaji wa kiotomatiki haupaswi kurudisha mara moja eneo la kuonyesha chini.

Kutumia mipangilio ya mwendo kwa usawa

Mradi hutoa mipangilio minne ya spring iliyorekebishwa katika ClaudeMotionPresets.ts. Unapotengeneza kipengele kipya, tumia tena Bouncy, Snappy, Gentle au Heavy Snap badala ya kuweka kwa kubahatisha ugumu na unyevu wa kila uhuishaji. Hii hufanya vitufe, paneli, kunasa wakati wa kuburuta na mpito wa vipengele vinavyoshirikiwa kudumisha lugha moja ya kifizikia.

Kushughulikia kwa usahihi kuburuta vigawanyo vya iframe

Unapoburuta upau wa kugawanya juu ya iframe, iframe inaweza kunasa matukio ya kiashiria na kusababisha kuburuta kukatike. ArtifactsSplitPaneResizer huwasha utaratibu wa kuzuia kunaswa kwa matukio wakati wa kuanza kuburuta, pamoja na ukanda wa kutosogeza wa 4px, vizuizi vya kingo na kunasa katikati kwa kubofya mara mbili. Ikiwa programu ina onyesho la kukagua la Artifacts, tumia tena moduli hii badala ya kusikiliza tu matukio ya kipanya kwenye upau wa kugawanya wenyewe.

Kuhifadhi urambazaji kamili kwa watumiaji wa kibodi

useClaudeRovingFocus inasaidia urambazaji wa vitufe vya mwelekeo wa mwelekeo mmoja au miwili, kuruka hadi mipaka kwa Home na End, pamoja na kuakisi kwa RTL. Unapotengeneza gridi ya miundo, orodha ya viambatisho au safu za kadi za zana, unapaswa pia kudumisha maana sahihi ya ARIA na hali ya fokasi inayoonekana.

Kushughulikia udhibiti wa kiwango cha miundo na hitilafu za huduma

useRateLimitBackoff inalenga majibu ya 429 na 503, na hutoa kuchelewesha kwa kielelezo kilichokatwa, kuingiza mtikisiko na utaratibu wa kurejesha kiotomatiki baada ya kuvunja mzunguko mara tatu. Inafaa kwa safu ya maombi ya miundo, lakini biashara bado inapaswa kuamua kulingana na muundo wake wa majibu ya API wakati wa kujaribu tena, wakati wa kuonyesha hitilafu na wakati wa kumruhusu mtumiaji kurejesha kwa mkono.

Kujifunza kwa kina kupitia mwongozo wa kiufundi

Mbali na msimbo wa chanzo wa vipengele, hazina pia hutoa mwongozo wa kiufundi wa mfumo wa usanifu wenye zaidi ya mistari 3,000. Inapendekezwa kuusoma kwa mpangilio ufuatao:

1. Anza kwa kusoma falsafa ya usanifu, ngazi za rangi za Surface, jedwali la pembe za mviringo na kanuni za mipaka ya mstari mwembamba.
2. Kisha jifunze vitufe, vidhibiti vya sehemu, viashiria vya hali na visanduku vya mazungumzo vya uthibitishaji.
3. Baadaye chunguza ingizo la mazungumzo, walinzi wa CJK, kubadilisha modeli na mashine ya hali ya MCP.
4. Unapohitaji uhuishaji changamano, tazama vigezo vya spring, mwanga wa mazingira na vinyago vya kusogeza.
5. Unapotengeneza programu za eneo-kazi, zana za media au nafasi za ushirikiano, soma sura inayolingana ya usanifu wa mfumo.

Mwongozo kamili unapatikana katika docs/Claude Design System (CDS).md. Kazi ya uchanganuzi wa kinyume ya mradi ilikamilishwa kwa kutumia REA.

Kushirikiana na AI Coding Agent

Hazina hutoa faili za AGENTS.md, CLAUDE.md, .cursorrules na faili za maagizo ya Copilot. Unapotumia zana kama Cursor, Claude Code au GitHub Copilot kutengeneza kiolesura kipya, unaweza kumtaka Agent afuate tokeni zilizopo za hazina, mipangilio ya spring, kanuni za mipaka na sheria za kulinda mbinu ya kuingiza.

Mfano wa agizo: Tafadhali fuata kwa ukamilifu kanuni za AGENTS.md katika hazina hii, na utumie tokeni za usanifu wa CDS Terracotta pamoja na mipangilio ya spring ya ClaudeMotionPresets kujenga kipengele cha sasa.

Muhtasari

open-claude-ui hupanga tokeni za kuona, vidhibiti vya mazungumzo, fizikia ya mwendo, mwingiliano wa media anuwai na usanifu wa eneo-kazi wa mteja wa AI kuwa moduli zinazoweza kutumika tena. Njia thabiti zaidi ya kuunganisha ni kuthibitisha kwanza matokeo kupitia Storybook ya nje ya mtandao, kisha kuleta CSS ya mandhari na upanuzi wa Tailwind, na hatimaye kuanza kuunganisha vipengele vya msingi kama kisanduku cha kuingiza mazungumzo, kibadilishaji cha modeli na kontena la kusogeza. Kwa hali changamano kama matokeo yanayotiririshwa, ingizo la CJK, kuburuta iframe na urambazaji wa kibodi, tumia tena Hooks na mashine za hali zilizopo kwenye hazina kadiri iwezekanavyo badala ya kunakili tu mitindo ya juu juu.